Depuração Sistemática

Quando Usar

Use esta habilidade quando precisar de uma metodologia de depuração em quatro fases com análise de causa raiz. Use ao investigar bugs, corrigir falhas de teste ou solucionar comportamentos inesperados. Enfatiza NENHUMA CORREÇÃO SEM ANTES IDENTIFICAR A CAUSA RAIZ.

Princípio Central

NENHUMA CORREÇÃO SEM ANTES INVESTIGAR A CAUSA RAIZ.

Nunca aplique correções focadas em sintomas que mascaram problemas subjacentes. Entenda POR QUE algo falha antes de tentar corrigi-lo.

A Estrutura de Quatro Fases

Fase 1: Investigação da Causa Raiz

Antes de tocar em qualquer código:

1. Leia as mensagens de erro detalhadamente - Cada palavra importa
2. Reproduza o problema de forma consistente - Se você não consegue reproduzir, não consegue verificar uma correção
3. Examine as mudanças recentes - O que mudou antes disso começar a falhar?
4. Colete evidências de diagnóstico - Logs, rastros de pilha (stack traces), despejos de estado (state dumps)
5. Rastreie o fluxo de dados - Siga a cadeia de chamadas para encontrar onde os valores incorretos se originam

Técnica de Rastreamento de Causa Raiz:

1. Observe the symptom - Where does the error manifest?
2. Find immediate cause - Which code directly produces the error?
3. Ask "What called this?" - Map the call chain upward
4. Keep tracing up - Follow invalid data backward through the stack
5. Find original trigger - Where did the problem actually start?

Princípio chave: Nunca corrija problemas apenas onde os erros aparecem — sempre rastreie até o gatilho original.

Fase 2: Análise de Padrões

1. Localize exemplos que funcionam - Encontre código semelhante que funciona corretamente
2. Compare as implementações completamente - Não apenas passe os olhos
3. Identifique as diferenças - O que é diferente entre o que funciona e o que está quebrado?
4. Entenda as dependências - Do que este código depende?

Fase 3: Hipótese e Teste

Aplique o método científico:

1. Formule UMA hipótese clara - "O erro ocorre porque X"
2. Desenhe um teste mínimo - Mude UMA variável por vez
3. Preveja o resultado - O que deveria acontecer se a hipótese estiver correta?
4. Execute o teste - Execute e observe
5. Verifique os resultados - Comportou-se como previsto?
6. Itere ou prossiga - Refine a hipótese se estiver errada, implemente se estiver certa

Fase 4: Implementação

1. Crie um caso de teste que falha - Captura o comportamento do bug
2. Implemente uma única correção - Aborde a causa raiz, não os sintomas
3. Verifique se o teste passa - Confirma que a correção funciona
4. Execute a suíte de testes completa - Garanta que não há regressões
5. Se a correção falhar, PARE - Reavalie a hipótese

Regra crítica: Se TRÊS ou mais correções falharem consecutivamente, PARE. Isso sinaliza problemas arquiteturais que exigem discussão, não mais correções.

Sinais de Alerta - Violações de Processo

Pare imediatamente se você se pegar pensando:

• "Correção rápida por enquanto, investigo depois"
• "Mais uma tentativa de correção" (após múltiplas falhas)
• "Isso deveria funcionar" (sem entender por quê)
• "Deixa eu só tentar..." (sem hipótese)
• "Funciona na minha máquina" (sem investigar a diferença)

Sinais de Problemas Mais Profundos

Correções consecutivas revelando novos problemas em áreas diferentes indicam problemas arquiteturais:

• Pare de aplicar correções
• Documente o que você encontrou
• Discuta com a equipe antes de prosseguir
• Considere se o design precisa ser repensado

Cenários Comuns de Depuração

Falhas de Teste

1. Read the FULL error message and stack trace
2. Identify which assertion failed and why
3. Check test setup - is the test environment correct?
4. Check test data - are mocks/fixtures correct?
5. Trace to the source of unexpected value

Erros em Tempo de Execução

1. Capture the full stack trace
2. Identify the line that throws
3. Check what values are undefined/null
4. Trace backward to find where bad value originated
5. Add validation at the source

"Funcionava antes"

1. Use git bisect to find the breaking commit
2. Compare the change with previous working version
3. Identify what assumption changed
4. Fix at the source of the assumption violation

Falhas Intermitentes

1. Look for race conditions
2. Check for shared mutable state
3. Examine async operation ordering
4. Look for timing dependencies
5. Add deterministic waits or proper synchronization

Checklist de Depuração

Antes de declarar um bug como corrigido:

• Causa raiz identificada e documentada
• Hipótese formulada e testada
• Correção aborda a causa raiz, não os sintomas
• Teste que falha criado que reproduz o bug
• Teste agora passa com a correção
• Suíte de testes completa passa
• Nenhuma racionalização de "correção rápida" utilizada
• Correção é mínima e focada

…