Systematic Debugging - Root Cause Analysis

Esta skill implementa um processo sistemático de debugging em 4 fases para encontrar e corrigir bugs de forma eficiente.

Princípio Fundamental

Debugging não é adivinhar. É um processo científico de eliminação.

code

┌─────────────────────────────────────────────────────────────┐
│  NUNCA:  "Acho que o problema é X, vou mudar e ver"        │
│  SEMPRE: "Vou coletar evidências para confirmar a causa"   │
└─────────────────────────────────────────────────────────────┘

As 4 Fases do Debugging Sistemático

Fase 1: REPRODUZIR (Obrigatório)

code

┌─────────────────────────────────────────────────────────────┐
│  🎯 OBJETIVO: Conseguir reproduzir o bug consistentemente   │
└─────────────────────────────────────────────────────────────┘

Checklist:

• Consigo reproduzir o bug?
• Quais são os passos exatos?
• É intermitente ou consistente?
• Em qual ambiente ocorre? (dev, staging, prod)
• Desde quando começou? (qual commit/deploy)

Perguntas Críticas:

•O que o usuário estava fazendo?
•Quais dados estavam envolvidos?
•Qual era o estado do sistema?

Output Esperado:

markdown

## Reprodução do Bug
- **Passos:** [1, 2, 3...]
- **Frequência:** [sempre | às vezes | raro]
- **Ambiente:** [dev | staging | prod]
- **Primeiro relato:** [data/commit]

Fase 2: ISOLAR (Eliminar Variáveis)

code

┌─────────────────────────────────────────────────────────────┐
│  🎯 OBJETIVO: Reduzir o espaço de busca ao mínimo          │
└─────────────────────────────────────────────────────────────┘

Técnicas de Isolamento:

Técnica	Quando Usar	Como
Binary Search	Bug em fluxo longo	Divida o fluxo ao meio, teste cada metade
Git Bisect	Bug em commit recente	`git bisect` para encontrar commit culpado
Feature Flags	Bug em feature específica	Desabilite features até isolar
Simplificação	Bug em dados complexos	Reduza dados ao mínimo que reproduz

Perguntas para Isolamento:

•Frontend ou Backend?
•Código ou Dados?
•Novo código ou Regressão?
•Ambiente específico ou todos?

Comando Útil - Git Bisect:

bash

git bisect start
git bisect bad HEAD
git bisect good <commit-que-funcionava>
# Git vai fazer binary search nos commits

Fase 3: DIAGNOSTICAR (Encontrar Root Cause)

code

┌─────────────────────────────────────────────────────────────┐
│  🎯 OBJETIVO: Entender POR QUE o bug acontece              │
└─────────────────────────────────────────────────────────────┘

Ferramentas de Diagnóstico:

Ferramenta	Propósito
Console.log / Print	Rastrear fluxo de execução
Debugger (breakpoints)	Inspecionar estado em tempo real
Stack trace	Entender cadeia de chamadas
Logs de produção	Contexto do erro real
Network tab	Verificar requests/responses

Framework de Análise:

code

┌─────────────────────────────────────────────────────────────┐
│  1. WHAT: O que está acontecendo de errado?                │
│  2. WHERE: Onde no código o erro ocorre?                   │
│  3. WHEN: Quando/sob quais condições?                      │
│  4. WHY: Por que o código se comporta assim?               │
│  5. HOW: Como o estado chegou a esse ponto?                │
└─────────────────────────────────────────────────────────────┘

5 Whys Technique:

code

Bug: Usuário não consegue salvar
  Why 1: API retorna 500
  Why 2: Database query falha
  Why 3: Coluna não existe
  Why 4: Migration não foi aplicada
  Why 5: Deploy script não roda migrations

ROOT CAUSE: Deploy script incompleto

Fase 4: CORRIGIR (E Prevenir)

code

┌─────────────────────────────────────────────────────────────┐
│  🎯 OBJETIVO: Corrigir o bug E prevenir recorrência        │
└─────────────────────────────────────────────────────────────┘

Checklist de Correção:

• Fix resolve o root cause (não só o sintoma)?
• Fix não introduz novos bugs?
• Teste automatizado cobre o cenário?
• Documentação atualizada se necessário?

Template de Fix:

markdown

## Bug Fix: [Título]

### Root Cause
[Explicação do que causava o bug]

### Solução
[O que foi mudado e por quê]

### Testes Adicionados
- [ ] Teste que reproduz o bug original
- [ ] Teste de regressão

### Prevenção Futura
[O que fazer para evitar bugs similares]

Padrões Comuns de Bugs

1. Race Conditions

code

Sintoma: Bug intermitente, difícil de reproduzir
Causa: Operações assíncronas sem sincronização
Solução: Locks, transações, ou sequenciamento

2. Off-by-One

code

Sintoma: Funciona para maioria, falha em edge cases
Causa: Índices ou limites incorretos
Solução: Revisar loops, arrays, e condições de borda

3. Null/Undefined Reference

code

Sintoma: "Cannot read property X of undefined"
Causa: Dados ausentes não tratados
Solução: Validação defensiva, optional chaining

4. State Corruption

code

Sintoma: Estado inconsistente após operações
Causa: Mutação direta, falta de imutabilidade
Solução: Imutabilidade, transações

5. Environment Mismatch

code

Sintoma: Funciona local, falha em prod
Causa: Diferenças de ambiente (vars, versões, dados)
Solução: Padronizar ambientes, containerização

Anti-Patterns de Debugging

Anti-Pattern	Problema	Solução
Shotgun Debugging	Mudar coisas aleatoriamente	Seguir as 4 fases
Printf Everywhere	Logs sem estratégia	Logs direcionados pela hipótese
Blame Game	Culpar outros/libs	Assumir que o bug é seu até provar contrário
Quick Fix	Corrigir sintoma, não causa	Sempre buscar root cause
Solo Debugging	Debugar sozinho por horas	Pedir ajuda após 30min travado

Regra dos 30 Minutos

code

┌─────────────────────────────────────────────────────────────┐
│  Se você está travado no mesmo bug por mais de 30 minutos: │
│                                                             │
│  1. Pare e documente o que você sabe                       │
│  2. Peça uma segunda opinião (rubber duck ou colega)       │
│  3. Faça uma pausa de 10 minutos                           │
│  4. Volte com perspectiva fresca                           │
└─────────────────────────────────────────────────────────────┘

Checklist Final

Antes de Começar

• Bug está claramente definido?
• Tenho acesso aos logs/ambiente necessário?
• Sei quando o bug começou?

Durante o Debugging

• Estou seguindo as 4 fases em ordem?
• Estou documentando minhas descobertas?
• Estou testando uma hipótese por vez?

Depois do Fix

• Bug original está corrigido?
• Não introduzi novos bugs?
• Teste automatizado adicionado?
• Root cause documentado?

Esta skill ativa AUTOMATICAMENTE quando:

•Usuário menciona "bug", "erro", "debug", "não funciona"
•Discussão sobre investigação de problemas
•Análise de stack traces ou logs de erro