Uma checklist de depuração

Percorra estes passos em ordem. Pular direto para "conserta" é o que faz a IA girar em círculos.

1. Reproduza de forma confiável. Encontre os passos exatos que fazem o bug acontecer toda vez. Um bug que você não consegue reproduzir é um bug que você não consegue confirmar que corrigiu — você vai ficar só chutando se ele sumiu ou não. Se ele acontece de forma intermitente, procure a variável que muda o resultado: uma entrada específica, um estado logado versus deslogado, uma rede lenta.
2. Leia o erro de verdade. Não passe os olhos por cima. A mensagem de erro e o topo do stack trace geralmente indicam o arquivo e a linha onde algo deu errado. Iniciantes costumam rolar a tela passando pela frase mais útil da tela porque ela parece intimidadora.
3. Reúna o contexto. Colete o texto do erro, o stack trace, o código relevante e uma descrição de uma linha do que você esperava.
4. Entregue o quadro completo à IA. Cole tudo isso numa única mensagem. Deixe que ela forme uma hipótese.
5. Forme uma hipótese, não uma correção. Pergunte "o que poderia causar isso?" antes de "conserte isso." Uma correção errada baseada numa teoria errada desperdiça tempo — e às vezes adiciona um segundo bug em cima do primeiro.
6. Adicione registros (logging) para testar a hipótese. Confirme o que o código está realmente fazendo antes de mudá-lo.
7. Faça busca binária no problema. Reduza onde ele quebra cortando repetidamente ao meio a área suspeita.
8. Corrija a causa raiz, não o sintoma. Garanta que a correção resolva por que quebrou, não apenas o defeito visível.
9. Verifique a correção e cheque por regressões. Refaça os passos de reprodução. Depois garanta que funcionalidades próximas ainda funcionam — uma regressão é quando uma correção quebra silenciosamente algo que costumava funcionar, como consertar um vazamento e estourar um cano ao lado.

Essa checklist é, na verdade, um único ciclo que você percorre até o bug sumir. Cada etapa entrega evidência para a próxima, e uma verificação que falha só te manda de volta ao ciclo com o que você aprendeu:

   ┌──────────────┐
   │  REPRODUCE   │  make it happen every time
   └──────┬───────┘
          ▼
   ┌──────────────┐
   │ READ ERROR + │  what does it actually say?
   │   GATHER     │  collect trace + code + context
   └──────┬───────┘
          ▼
   ┌──────────────┐
   │ HYPOTHESIS   │  "what could cause this?"
   └──────┬───────┘
          ▼
   ┌──────────────┐
   │ CONFIRM w/   │  add a log, get evidence
   │   LOGGING    │
   └──────┬───────┘
     wrong│  correct
   ┌──────┘ guess   ▼
   │            ┌──────────────┐
   │ (new       │  FIX root    │  not the symptom
   │  theory)   │    cause     │
   │            └──────┬───────┘
   │                   ▼
   │            ┌──────────────┐    fails / regression
   └────────────┤   VERIFY     │──────────┐
                │ + regressions│          │
                └──────┬───────┘          │
                       │ passes           │
                       ▼          ◀───────┘
                    ✔ DONE      (loop back around)

A ordem não é arbitrária. Cada etapa produz a evidência de que a próxima precisa. Reproduzir te dá algo para ler; ler te dá contexto para reunir; o contexto dá à IA algo sobre o que formar hipóteses. Pule uma etapa e você estará alimentando a próxima com um buraco.