~/discoveries/work 2026-11-21
De um problema repetido a um lint catalogado
O protocolo que transforma um erro recorrente ou um pedido repetido em uma correção certificada, uma guarda e um lint compartilhado, e por que ele espera um sim explícito.
- harness
- learning-loop
- lints
- process
- ~/project/versatile-sh
A equipe aprende uma vez
O princípio do harness é uma linha: tudo que uma pessoa ensina à IA deve chegar às outras três sem que ninguém repita, e um erro corrigido deve se tornar impossível, não lembrado. Memória em uma máquina não é aprendizado. Uma regra só em prosa será quebrada de novo.
O protocolo tem sete passos: reconhecer, corrigir a causa raiz, certificar com evidência, pedir ao usuário que confirme, codificar como guarda, registrar no lar compartilhado, compartilhar. Este post é sobre os três que me surpreenderam quando li os docs.
Nomeie a classe, não a instância
O passo 1 diz para enunciar o problema como uma classe. O exemplo do doc é valores de cor crus em componentes, não o header é azul. Parece conselho de estilo, mas decide se a guarda pode existir. Uma guarda precisa de um formato para casar.
Isso também força uma busca. O catálogo de lints é verificado primeiro, porque a classe pode já ter um para ativar. Um lint escrito duas vezes são dois lints que vão discordar.
Só um sim explícito destrava a guarda
Depois da correção e da evidência, o agente faz uma pergunta. A certificação é do agente. A confirmação é da pessoa. Então três desfechos:
| O usuário | Então |
|---|---|
| Diz sim | A guarda é escrita e registrada; o issue é marcado como corrigido e confirmado, com o comando da guarda |
| Não responde | O trabalho continua. A correção e o teste de regressão ficam; o issue diz corrigido, não confirmado; ainda sem guarda para a classe inteira |
| Diz não | O issue reabre com o que foi observado, e o diagnóstico é refeito |
O motivo está no doc: uma guarda construída sobre um diagnóstico não confirmado crava um palpite no código. Acho isso mais convincente que o argumento usual para perguntar, que é educação.
A guarda precisa morder, e ter um só lar
- Provar que morde. Reintroduzir o erro e ver a guarda falhar. Uma guarda que nunca falhou não prova nada.
- Ligá-la ao único comando de check do projeto.
- Escrever a mensagem de falha como uma instrução: o que está errado, onde, o que fazer em vez disso.
- Registrá-la no catálogo de lints na mesma unidade de trabalho, como uma única implementação compartilhada. Um projeto ativa um lint referenciando-o, nunca copiando.
O próprio catálogo mostra o custo de pular o último ponto. Várias entradas antigas estão marcadas como cópias por repositório ou implementação não verificada, e o doc chama isso de dívida que a regra existe para impedir.
Ninguém precisa lembrar de iniciar
Um hook UserPromptSubmit procura marcadores de repetição no prompt do usuário, como já te falei, de novo ou sempre, em português e inglês. Ele adiciona uma linha de contexto apontando para o passo 1. Nunca bloqueia. Também ignora notificações automáticas, uma correção que entrou em 2026-11-21 (#196). A checklist de conhecimento de todo pull request faz a mesma pergunta pelo outro lado.
Um caso concreto do loop inteiro, o lint de view transition, está em seu próprio post. Não tenho uma contagem de quantos lints o loop produziu; o catálogo tem 19 entradas, mas várias são anteriores ao protocolo.