Depuração Sistemática

Visão Geral

Correções aleatórias desperdiçam tempo e criam novos bugs. Soluções rápidas mascaram problemas subjacentes.

Princípio Central: Investigue antes de adivinhar e separe um reparo verificado de uma mitigação temporária. Durante um incidente, um rollback autorizado ou uma ação de contenção pode restaurar o serviço enquanto o trabalho de causa raiz continua.

Violar a letra deste processo é violar o espírito da depuração.

A Lei de Ferro

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

Comece com a falha observável e a verificação de evidências úteis mais simples. Rotule explicitamente qualquer mitigação de emergência e preserve evidências para a investigação posterior da causa raiz.

Quando Usar

Use para QUALQUER problema técnico:

• Falhas de teste
• Bugs em produção
• Comportamento inesperado
• Problemas de desempenho
• Falhas de compilação
• Problemas de integração

Use isso ESPECIALMENTE quando:

• Sob pressão de tempo (emergências tornam a adivinhação tentadora)
• "Apenas uma correção rápida" parece óbvia
• Você já tentou várias correções
• A correção anterior não funcionou
• Você não entende completamente o problema

Não pule quando:

• O problema parece simples (bugs simples também têm causas raiz)
• Você está com pressa (apressar garante retrabalho)
• O gerente quer que seja corrigido AGORA (sistemático é mais rápido do que ficar girando em falso)

As Quatro Fases

Você DEVE completar cada fase antes de prosseguir para a próxima.

Fase 1: Investigação da Causa Raiz

ANTES de tentar QUALQUER correção:

1. Leia as Mensagens de Erro Cuidadosamente

   • Não pule erros ou avisos
   • Eles geralmente contêm a solução exata
   • Leia os rastros de pilha completamente
   • Anote números de linha, caminhos de arquivo, códigos de erro

2. Reproduza Consistentemente

   • Você consegue acioná-lo de forma confiável?
   • Quais são os passos exatos?
   • Acontece toda vez?
   • Se não for reproduzível → colete mais dados, não adivinhe

3. Verifique Mudanças Recentes

   • O que mudou que poderia causar isso?
   • git diff, commits recentes
   • Novas dependências, mudanças de configuração
   • Diferenças ambientais

4. Colete Evidências em Sistemas Multi-Componentes

   QUANDO o sistema tem múltiplos componentes (CI → build → signing, API → service → database):

   ANTES de propor correções, adicione instrumentação de diagnóstico:

   For EACH component boundary:
     - Record allowed field names, sizes, statuses and correlation IDs
     - Redact secrets and private payloads before logging
     - Verify environment/config propagation
     - Check state at each layer
   
   Run once to gather evidence showing WHERE it breaks
   THEN analyze evidence to identify failing component
   THEN investigate that specific component
   

   Exemplo (sistema multi-camada):

   # In each relevant process, report presence only; never dump secret values.
   if [ -n "${IDENTITY:-}" ]; then
     echo 'IDENTITY is set'
   else
     echo 'IDENTITY is absent or empty'
   fi
   
   # Read-only validation of an already-built artifact, when available.
   codesign --verify --verbose=2 "$APP"
   

   Interpretação: Compare as verificações de presença nas fronteiras reais do fluxo de trabalho/compilação. A verificação de artefatos não prova por si só que a identidade de assinatura correta foi propagada.

5. Rastreie o Fluxo de Dados

   QUANDO o erro está no fundo da pilha de chamadas:

   Veja root-cause-tracing.md neste diretório para a técnica completa de rastreamento reverso.

   Versão rápida:

   • De onde vem o valor ruim?
   • O que chamou isso com valor ruim?
   • Continue rastreando para cima até encontrar a origem
   • Corrija na origem, não no sintoma

Fase 2: Análise de Padrões

Encontre o padrão antes de corrigir:

1. Encontre Exemplos de Funcionamento

   • Localize código de funcionamento semelhante na mesma base de código
   • O que funciona que é semelhante ao que está quebrado?

2. Compare com Referências

   • Se estiver implementando um padrão, leia a implementação de referência COMPLETAMENTE
   • Não passe por cima - leia cada linha
   • Entenda o padrão completamente antes de aplicar

3. Identifique Diferenças

   • O que é diferente entre o que funciona e o que está quebrado?
   • Liste cada diferença, por menor que seja
   • Não assuma "isso não pode importar"

4. Entenda as Dependências

   • Quais outros componentes isso precisa?
   • Quais configurações, ambiente?
   • Quais suposições ele faz?

Fase 3: Hipótese e Teste

Método científico:

1. Formule uma Única Hipótese

   • Declare claramente: "Eu acho que X é a causa raiz porque Y"
   • Escreva isso
   • Seja específico, não vago

2. Teste Minimamente

   • Faça a MENOR mudança possível para testar a hipótese
   • Uma variável por vez

…