chimera-reproduce-before-diagnosing
Um diagnóstico é uma afirmação sobre uma máquina que você não rodou. Reproduza a falha em um comando curto primeiro — especialmente quando o diagnóstico veio de outra pessoa.
Conferida por quem revisou e leu o cartão, não reivindicada pelo próprio arquivo. Um cartão que o agente destila durante uma execução que consumiu conteúdo não confiável nasce contaminado e fica retido para revisão antes de alguma vez ser recuperado.
Quando ele vem à mente
- chegou um relato de bug
- outro agente explicou a causa
- o traceback aponta para um arquivo
- prestes a corrigir algo sem ter visto falhar
Evite e Verifique são onde costuma estar o valor. Faça é a seção que todo mundo escreve.
O corpo do cartão acima é uma tradução. O original em inglês é o que a CLI importa, o que o agente lê em execução e o que o hash abaixo atesta.
Gatilho
Você está prestes a mudar código por causa de uma falha que você não viu acontecer pessoalmente: um job de CI vermelho, um trecho de log numa issue, a descrição de um usuário, ou — o caso de que este card realmente trata — um diagnóstico confiante entregue a você por um revisor, um sub-agente, ou uma ferramenta de análise estática, completo com arquivo e número de linha.
Não se aplica quando a falha já é um comando. Um teste que falha localmente quando você o roda é uma reprodução; não construa uma segunda. Também não se aplica a trabalho que não tem falha nenhuma dentro — uma feature nova, um refactor, uma pergunta de design. Esses não têm o que reproduzir.
Faça
- Escreva a menor coisa que falha e que pode ser rodada sozinha: um script, um node id de pytest, uma invocação de CLI. "Rode a suíte e olhe o terceiro erro" não serve — você vai passar direto pelo erro todas as vezes.
- Rode. Copie a saída real para as suas notas: o tipo da exceção, o valor errado ao lado do esperado, o código de saída. Não o seu resumo dela.
- Agora enuncie o diagnóstico, e imediatamente tente matá-lo. Coloque um
raise RuntimeError("here")no topo da função que o diagnóstico culpa e rode a reprodução de novo. Se a falha original continuar aparecendo inalterada, aquela função não está no caminho que falha e o diagnóstico está errado, por melhor que fosse a argumentação. - Corrija, rode o mesmo comando de novo, e mantenha a reprodução como teste na mesma mudança. Uma reprodução apagada depois da correção não consegue te avisar quando a correção for revertida.
Evite
Editar o frame do traceback que você reconhece. O frame que você reconhece é aquele que você já leu antes, não aquele que está errado, e uma edição plausível ali costuma fazer o sintoma se mudar para outro lugar — o que então é lido como progresso.
Evite herdar um diagnóstico como se fosse fato. Uma explicação recebida de outra pessoa é texto, e o processo que produz uma explicação errada e fluente é o mesmo que produz uma certa e fluente, então a fluência não carrega informação nenhuma sobre qual das duas você recebeu. Trate isso como uma hipótese com um nome anexado: útil para ordenar o que tentar, sem valor como evidência.
# reviewer says the cache key is missing the tenant id
key = f"{tenant.id}:{user.id}"
# yes — first make the failure appear on demand
# repro.py: two tenants, same user id, assert the second read misses
E evite o reflexo de rodar de novo até ficar verde numa falha intermitente. Rodar de novo não diagnostica uma corrida, esconde uma, e converte um bug reproduzível uma vez num bug que ninguém consegue reproduzir.
Verifique
Antes de escrever a correção, responda sim ou não: eu consigo fazer esta falha acontecer de novo, agora, com um comando? Se não, você não está depurando, está especulando com um editor aberto.
Depois da correção: o mesmo comando passa agora, e você o viu falhar antes com os próprios olhos? Uma correção validada apenas pela suíte ficando verde prova que a suíte está verde — o que ela pode já estar pelo motivo errado, se o caso que falhava nunca esteve na suíte.
Risco
Algumas falhas são genuinamente caras de reproduzir: uma condição de corrida que aparece uma vez por dia, um estado que só existe em produção, um crash seis horas dentro de um job longo. Insistir numa reprodução barata ali queima mais do que o bug custa. Estabeleça um limite de tempo, e se o limite estourar, diga claramente que a correção não está verificada em vez de descrevê-la como confirmada.
A armadilha mais sutil é a minimização em excesso. Um script reduzido pode passar a falhar por um motivo diferente do original, e aí você corrige o brinquedo. Proteja-se aplicando a correção também ao caminho original que falhava, e confirmando que o sintoma original desaparece ali — o caso minimizado é uma ferramenta para encontrar a causa, nunca a prova de que era a causa.
Como usar
O cartão é dado. Clone o repositório e importe pelo caminho — o que chega pela rede é tratado como contaminado e fica retido para aprovação, que é o comportamento desejável e a razão de não haver um instalador de uma linha aqui.
git clone https://github.com/brcampidelli/chimera-agent.gitchimera skills-import chimera-agent/skills/chimera-reproduce-before-diagnosing/SKILL.mdIntegridade
SHA-256 do arquivo como publicado. Quem importa pode conferir que o que recebeu é o que esta página mostrou.
9d70fa5a61992e3b79a2d0ab2afb592c41a7b63274efbdca0afec1724a5b8338