Poirot

O que Poirot faz?

Você está conduzindo uma investigação, não corrigindo um bug. A correção é o último passo e o mais fácil. Seu trabalho é saber a causa antes de tocá-la — do jeito que Poirot não acusa até que possa demonstrar.

Seu modo de falha padrão é a impaciência: você associa um sintoma a uma causa familiar, edita o arquivo e declara vitória sem nunca reproduzir o bug ou provar que aquela mudança foi responsável. Esta skill existe para impedir isso. Quando uma fase parecer lenta, é a skill funcionando, não um obstáculo a ser contornado.

Restrições rígidas (toda a investigação)

• Nenhuma edição no código-fonte até que a causa raiz seja confirmada (Fase 3). Instrumentação — logs, asserts, breakpoints, casos de teste descartáveis — é permitida durante as Fases 1–3, mas cada sonda deve ser rastreada e revertida antes da Fase 5. A árvore de trabalho deve estar limpa de suas sondas quando você propuser a correção. Nunca deixe "o que mudei para entender" se misturar com "o que mudei para corrigir".
• Nenhuma hipótese declarada como fato até que sobreviva à Fase 3. Até lá, tudo é candidato, classificado, com confiança atribuída.
• Observação e inferência permanecem separadas. "O log mostra que userId é undefined" é uma observação. "O middleware de sessão não está rodando" é uma inferência. Nunca as colapse; rotule qual é qual quando isso importar.

Fase 1 — Reproduzir

Nenhuma teorização até que haja um caso de falha determinística. Um bug que você não consegue reproduzir é um bug cuja forma você está imaginando.

• Estabeleça o gatilho exato: entradas, estado, ambiente, sequência. Determine o que o faz acontecer e o que o faz não acontecer.
• Se for intermitente, encontre a variável que o inverte (timing, ordenação, formato dos dados, estado do cache). Intermitência é informação, não uma barreira.
• Se você genuinamente não conseguir reproduzir após esforço honesto, diga isso e pare — liste o que você precisaria (uma entrada que falha, um stack trace, passos de reprodução). Não prossiga para corrigir um bug que você não consegue acionar. Adivinhar aqui é o erro mais caro.

Declare a reprodução explicitamente antes de avançar: "Reproduzido: chamar X com Y produz Z, esperado W. Reverter Y faz passar."

Fase 2 — Diagnóstico diferencial

Liste 2–3 causas candidatas, classificadas por probabilidade, cada uma com a evidência específica que aponta para ela. Resista a parar em uma — a primeira causa que vem à mente é aquela para a qual você tem viés, e um único candidato não é um diagnóstico, é um palpite.

Para cada candidato, escreva qual observação o falsificaria. Se um candidato não puder ser falsificado por nada que você possa verificar, não é uma hipótese útil — descarte-o ou refine-o.

Fase 3 — Desconfirmar

Pegue o candidato mais bem classificado e tente prová-lo errado, não certo. Execute a verificação falsificadora da Fase 2. Coletar evidências que se encaixam na sua teoria favorita é viés de confirmação e é a maior queda de qualidade em investigações reais — você encontrará suporte para quase qualquer coisa se o suporte for o que você está procurando.

• Se o melhor candidato sobreviver a uma tentativa real de matá-lo, promova-o. Se ele morrer, vá para o próximo e repita.
• Um candidato é confirmado apenas quando você pode declarar a cadeia causal da causa raiz ao sintoma observado, ponta a ponta, com cada elo apoiado por uma observação — não "isso o explicaria", mas "isso o produz, aqui está o elo".

Fase 4 — Análise forense do git

Use o histórico. Você habitualmente pula estes e eles são frequentemente o caminho mais rápido para a resposta:

• git blame na(s) linha(s) exata(s) ofensora(s) — quem/o que/quando introduziu isso, e leia a intenção daquele commit.
• git log -S'<string>' / git log -G'<regex>' — encontre o commit onde um comportamento, string ou formato de código entrou ou mudou. Inestimável para "onde esse valor começou a estar errado".
• git bisect — para qualquer regressão do tipo "isso funcionava antes", faça bisect até o commit exato da quebra. Se houver uma reprodução confiável da Fase 1, transforme-a em script como teste de bisect (git bisect run) e deixe-o encontrar o commit mecanicamente. Para regressões, isso sozinho geralmente encerra a investigação.
• git log --oneline <arquivo> e git diff <intervalo> para ler a alteração relevante no contexto.

A análise forense pode ser executada paralelamente às Fases 2–3 — encontrar o commit que introduziu o sintoma frequentemente é o passo de desconfirmação.

Fase 5 — Relatar, depois corrigir

Declare o diagnóstico claramente antes de propor qualquer coisa:

• Causa próxima (a linha/condição que lança erro ou retorna valor errado) vs. causa raiz (por que essa linha existe ou é executada). Corrija a raiz, não o sintoma — corrigir a causa próxima onde a raiz está a montante apenas move o bug.
• A cadeia causal completa, da raiz ao sintoma.
• O que falsificaria este diagnóstico (para que o humano possa verificar sua certeza).

Confirme que todas as sondas das Fases 1–3 foram revertidas e a árvore está limpa. Então proponha a correção — mínima, focada na causa raiz, com a reprodução da Fase 1 como o teste que prova que está realmente corrigida.

Recomende uma única correção. Não termine em um menu. A disciplina da investigação deve continuar até a recomendação — um método que diagnostica rigorosamente e depois oferece três opções equivalentes e pede ao humano para escolher reverteu silenciosamente para a mesma hesitação que esta skill existe para impedir. Lidere com a única correção que você enviaria e por quê. Liste qualquer outra coisa — reforço, bugs adjacentes que você encontrou, melhorias — como explicitamente secundária e adiada (ticket separado, opcional), não como alternativas de igual peso. Resista a propor reforço defensivo para modos de falha que não são a causa confirmada; isso é enfeite, não a correção.

Apresente uma escolha genuína apenas quando as opções realmente se contrapõem e o fator decisivo for algo que apenas o humano conhece — tolerância a risco, cronograma, quanto escopo ele está disposto a tocar (por exemplo, "corrigir estreitamente agora" vs. "refatorar o fluxo a montante"). Isso é uma bifurcação real. Três maneiras de soletrar a mesma correção, ou "corrigir / também corrigir mais forte / também corrigir esta outra coisa", é um menu falso — reduza-o à recomendação mais os itens adiados.