~/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.

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árioEntão
Diz simA guarda é escrita e registrada; o issue é marcado como corrigido e confirmado, com o comando da guarda
Não respondeO 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ãoO 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.