Diagnóstico de Bugs

Quando Usar

Use quando este fluxo de trabalho corresponder à solicitação do usuário: Use esta habilidade para seu fluxo de trabalho documentado.

Fonte: mattpocock/skills (MIT).

Uma disciplina para bugs difíceis. Pule fases apenas quando explicitamente justificado.

Ao explorar a base de código, leia CONTEXT.md (se existir) para obter um modelo mental claro dos módulos relevantes e verifique os ADRs na área que você está acessando.

Fase 1 — Construir um loop de feedback

Esta é a habilidade. Todo o resto é mecânico. Se você tiver um sinal apertado de sucesso/falha para o bug — um que fica vermelho neste bug — você encontrará a causa; bisseção, teste de hipóteses e instrumentação apenas o consomem. Se você não tiver um, nenhuma quantidade de análise de código o salvará.

Dedique um esforço desproporcional aqui. Seja agressivo. Seja criativo. Recuse-se a desistir.

Maneiras de construir um — tente-os nesta ordem aproximada

1. Teste com falha em qualquer ponto de junção que alcance o bug — unitário, de integração, e2e.
2. Script Curl / HTTP contra um servidor de desenvolvimento em execução.
3. Invocação de CLI com uma entrada de "fixture" (exemplo fixo), comparando a saída padrão com um "snapshot" conhecido.
4. Script de navegador sem cabeça (Playwright / Puppeteer) — controla a interface do usuário, afirma sobre DOM/console/rede.
5. Reproduzir um trace capturado. Salve uma solicitação de rede real / payload / log de eventos em disco; reproduza-o através do caminho do código isoladamente.
6. "Throwaway harness" (ferramenta descartável). Inicie um subconjunto mínimo do sistema (um serviço, dependências mockadas) que exercite o caminho do código do bug com uma única chamada de função.
7. Loop de propriedade / fuzzing. Se o bug for "saída às vezes errada", execute 1000 entradas aleatórias e procure o modo de falha.
8. "Bisection harness" (ferramenta de bisseção). Se o bug apareceu entre dois estados conhecidos (commit, conjunto de dados, versão), automatize "iniciar no estado X, verificar, repetir" para que você possa git bisect run.
9. Loop diferencial. Execute a mesma entrada através da versão antiga vs. nova (ou duas configurações) e compare as saídas.
10. Script bash HITL (Humano na Linha de Comando). Último recurso. Se um humano precisar clicar, guie-o com scripts/hitl-loop.template.sh para que o loop ainda seja estruturado. A saída capturada retorna para você.

Construa o loop de feedback correto e o bug estará 90% corrigido.

Aperte o loop

Trate o loop como um produto. Uma vez que você tenha um loop, aperte-o:

• Posso torná-lo mais rápido? (Cache de configuração, pular inicialização não relacionada, estreitar o escopo do teste.)
• Posso tornar o sinal mais nítido? (Afirmar sobre o sintoma específico, não "não travou".)
• Posso torná-lo mais determinístico? (Fixar tempo, semear RNG, isolar sistema de arquivos, congelar rede.)

Um loop instável de 30 segundos é pouco melhor do que nenhum loop; um loop determinístico de 2 segundos é apertado — um superpoder de depuração.

Bugs não determinísticos

O objetivo não é uma reprodução limpa, mas uma taxa de reprodução mais alta. Execute o gatilho em loop 100 vezes, paralelize, adicione estresse, estreite janelas de tempo, injete pausas. Um bug com 50% de instabilidade é depurável; 1% não é — continue aumentando a taxa até que seja depurável.

Quando você genuinamente não consegue construir um loop

Pare e diga isso explicitamente. Liste o que você tentou. Peça ao usuário: (a) acesso a qualquer ambiente que o reproduza, (b) um artefato capturado (arquivo HAR, dump de log, core dump, gravação de tela com timestamps), ou (c) permissão para adicionar instrumentação de produção temporária. Não prossiga para hipotetizar sem um loop.

Critério de conclusão — um loop apertado que fica vermelho

A Fase 1 é concluída quando o loop está apertado e capaz de ficar vermelho: você pode nomear um comando — um caminho de script, uma invocação de teste, um curl — que você já executou pelo menos uma vez (cole a invocação e sua saída), e que é:

• Capaz de ficar vermelho — ele controla o caminho real do código do bug e afirma o sintoma exato do usuário, para que possa ficar vermelho neste bug e verde assim que corrigido. Não "executa sem erros" — ele deve ser capaz de capturar este bug específico.
• Determinístico — o mesmo veredito a cada execução (bugs instáveis: uma taxa de reprodução alta e fixada, conforme acima).
• Rápido — segundos, não minutos.
• Executável pelo agente — você pode executá-lo sem supervisão; um humano no loop apenas via scripts/hitl-loop.template.sh.

Se você se pegar lendo código para construir uma teoria antes que este comando exista, pare — pular direto para uma hipótese é a falha exata que esta habilidade evita. Sem comando capaz de ficar vermelho, sem Fase 2.

Fase 2 — Reproduzir + Minimizar

Execute o loop. Veja-o ficar vermelho — o bug aparece.

Confirme:

…