Quebre os Ciclos de Correção de IA

Substitua o comportamento de "corrigir e tentar novamente" por um reparo limitado e produtor de evidências. Trate um patch alterado como progresso apenas quando um estado observável mudar.

Quando Usar Esta Habilidade

• Use quando um agente de codificação de IA cicla por patches semelhantes sem alterar a falha observada.
• Use quando um teste focado passa, mas o caminho de execução instalado, implantado, na UI, API, persistência ou outro caminho de execução real ainda falha.
• Use quando uma reivindicação de reparo precisa de um verificador que possa rejeitar um estado conhecido como ruim e um rollback que realmente restaurou a linha de base em uma cópia descartável.
• Não use para uma edição única, já compreendida, cuja verificação de aceitação exercite diretamente o comportamento completo reivindicado.

Estabeleça o contrato de reparo

Antes da primeira edição, registre:

• o defeito exato e o comportamento que o refutaria;
• a revisão, configuração, entrada e caminho de execução em teste;
• o comando de linha de base, resultado literal e status de saída;
• a verificação mais forte que observa diretamente o comportamento reivindicado;
• o comando de rollback e o estado que ele deve restaurar.

Salve a evidência bruta antes de normalizá-la. Redija credenciais, tokens, cookies, dados pessoais e URLs privadas. Nunca coloque segredos em um registro de impressão digital ou em um livro-razão comprometido.

Se o defeito não puder ser reproduzido, pare de editar. Relate INCONCLUSIVE com a observação ausente em vez de adivinhar uma correção.

Use um orçamento de três tentativas

Permita no máximo três tentativas de reparo para uma reivindicação de aceitação. Uma tentativa começa quando código, configuração, dependências, artefatos gerados ou expectativas de teste mudam. Inspeções e sondagens somente leitura não consomem uma tentativa.

Não reinicie o orçamento porque o agente reinicia, abre uma nova sessão, reescreve o mesmo patch, muda de modelo, limpa um cache ou renomeia a hipótese. Uma falha downstream recém-exposta ainda pertence ao mesmo orçamento de três tentativas, a menos que seja uma tarefa separadamente aceita.

Para cada tentativa, escreva estes campos antes da próxima edição:

Use o livro-razão de evidências como um registro copiável.

Imprima a falha observável

Imprima o que o sistema fez, não a explicação do agente. Construa um registro canônico a partir de:

{
  "schema_version": 1,
  "command": "the exact verification command",
  "input_digest": "digest or stable identifier of the tested input",
  "exit_code": 1,
  "failure_class": "stable-machine-readable-class",
  "stable_excerpt": "the smallest decisive output with volatile values removed",
  "real_path_state": "the directly observed state, or NOT_OBSERVED"
}

Mantenha a saída não editada ao lado deste registro higienizado. Remova timestamps, IDs de execução, códigos ANSI, portas aleatórias e caminhos temporários de stable_excerpt apenas quando eles não afetarem o defeito. Não normalize valores que possam distinguir duas causas.

Opcionalmente, calcule a impressão digital canônica SHA-256 a partir deste diretório de habilidades:

python3 scripts/fingerprint.py evidence/attempt-1.json

O auxiliar valida o registro, rejeita campos desconhecidos e imprime a impressão digital. Ele não executa comandos nem redige evidências.

O auxiliar usa apenas a biblioteca padrão do Python 3.9+. Ao alterá-lo, execute seus testes de regressão agrupados:

PYTHONDONTWRITEBYTECODE=1 python3 -m unittest scripts/test_fingerprint.py -v

A mesma impressão digital após um patch diferente significa que a falha observável não mudou. Uma mensagem cosmeticamente diferente com a mesma classe de falha, entrada, comando e estado de caminho real também conta como uma falha repetida quando o texto alterado é apenas dados voláteis. Não use um hash de patch na impressão digital do sintoma; registre-o separadamente para que edições diferentes não possam se disfarçar como resultados diferentes.

Mude a estratégia de causa raiz

Defina a decisão para SHIFT_CAUSE imediatamente quando qualquer um destes ocorrer:

• uma impressão digital do sintoma se repete;
• o patch muda, mas o estado decisivo não;

…