dev-debugging

Depuração — da falha à causa raiz, com prova

Depurar é eliminar hipóteses com evidência, não tentar consertos até um "pegar". Vale para teste vermelho, build quebrado, bug em produção e comportamento estranho sem erro nenhum.

Regra de parada

Quando algo inesperado acontece:

1. Pare de adicionar feature ou mudar código não relacionado — erro em cima de erro contamina o diagnóstico.
2. Guarde a evidência antes de mexer: mensagem completa, stack trace, log com horário, comando exato, commit (git rev-parse HEAD), dado de entrada.
3. Siga as cinco etapas abaixo em ordem. Pular etapa é o que transforma 20 minutos em uma tarde.
4. Só volte ao trabalho anterior depois do /verify-before-done.

1. Reproduzir

Sem reprodução não há como saber se a correção funcionou. Escreva os passos mínimos e fixe as três variáveis:

Variável	O que anotar
Passos	Sequência exata, do estado limpo até a falha (comando, clique, requisição)
Ambiente	Versões (Node, navegador, SO, dependências do lockfile), variáveis de ambiente, flags, local × CI × produção
Dado	Registro, payload ou arquivo que dispara a falha — e se ela some com outro dado

Para teste: rode só o teste que falha, isolado e em série (sem paralelismo), com saída detalhada — use o comando de teste do próprio repositório.

Não reproduz? Classifique antes de desistir:

• Tempo (corrida, timeout) → carimbo de tempo nos logs, atraso artificial para alargar a janela, rodar sob carga ou concorrência.
• Ambiente → comparar versões e variáveis lado a lado; tentar no CI, que é o ambiente limpo.
• Estado → estado vazando entre testes ou requisições (global, singleton, cache); rodar o cenário isolado × depois de outros.
• Aleatório de fato → log defensivo no ponto suspeito, alerta pela assinatura do erro, registrar as condições observadas e voltar quando repetir. Não "corrija" o que não reproduziu — relate como hipótese.

2. Localizar

Descubra onde antes de perguntar por quê.