Agent Skills: Debug & Fix (First-Run Resolution)

Debug & Fix (First-Run Resolution)

Objetivo

Encontrar a causa raiz de um bug e entregar correcao validada (reproducao + testes + verificacao de feature), minimizando risco de regressao e evitando "shotgun debugging".

Principios

1. Evidencia > intuicao. Nada de inventar stack traces, causas ou comportamentos: tudo deve ser suportado por logs, codigo, testes ou reproducoes.
2. Reproduzir primeiro. Sem reproducao, nao ha confirmacao de correcao.
3. Hipoteses explicitas. Toda acao deve estar ligada a uma hipotese que pode ser falsificada.
4. Mudancas minimas, impacto maximo. Corrigir na causa, nao no sintoma.
5. Fix so conta quando validado: repro original passa + testes passam + teste novo cobre o bug.
6. Instrumentacao disciplinada: logs temporarios com correlacao e remocao/flag apos diagnostico.
7. Cobertura de origens alternativas: confirmar que o bug nao e gerado por outro caller/path/config/ambiente.
8. Tempo de run e subordinado a qualidade do resultado: priorizar "resolver de primeira" com investigacao guiada.

Artefatos temporarios (por run)

Crie/atualize estes dois arquivos (na pasta de trabalho do agente) para manter foco e evitar alucinacao em contextos longos:

• WALKTHROUGH.md (diario de investigacao)
• TASKS.md (checklist executavel)

Ferramentas do repo (AERA)

• npm --prefix root-files run debug:doctor
• npm --prefix root-files run debug:cli report --json --out agent-report.json
• GET /api/debug/logs?limit=50 (backend ativo)

Template: WALKTHROUGH.md

• Contexto (o que quebrou, onde, impacto)
• Reproducao (passos, comandos, inputs, ambiente)
• Observacoes (logs/erros relevantes, com timestamps)
• Hipoteses (H1..Hn) + como falsificar
• Experimentos executados (o que rodou, resultado)
• Causa raiz (cadeia causal completa)
• Fix aplicado (o que mudou e por que)
• Validacao (repro + testes + checagens)
• Riscos/Regressoes (o que pode quebrar e mitigacao)
• Notas finais (o que ficou de hardening / follow-ups)

Template: TASKS.md

[ ] Entender sintomas e criterios de sucesso (Definition of Done) [ ] Reproduzir o bug (local/CI) ou criar repro sintetico/replay [ ] Coletar evidencia (logs, configs, versoes, inputs) [ ] Formular 2-5 hipoteses e plano de falsificacao [ ] Executar experimentos e reduzir espaco de busca [ ] Identificar causa raiz (nao so o sintoma) [ ] Implementar correcao minima e correta [ ] Criar/atualizar teste que falha antes e passa depois [ ] Rodar suite relevante (unit/integration/e2e/lint/build) [ ] Verificar feature funcionando no cenario real (ou simulado fiel) [ ] Checar origens alternativas (callers/paths/config/ambiente/cache/retry) [ ] Remover/flaggar instrumentacao temporaria [ ] Escrever resumo final (o que era, causa, fix, como validar)

Procedimento (loop de debug)

1) Enquadrar o problema (2-5 min)

• Definir claramente: sintoma, componente afetado, ambiente, frequencia, impacto.
• Escrever Definition of Done em 1-3 bullets (ex: "endpoint X retorna 200 com payload Y, sem regressao no fluxo Z").

2) Reproducao (prioridade maxima)

• Tentar reproduzir com passos minimos.
• Se nao reproduzir:
  • Capturar inputs reais (payload/headers/config) para replay.
  • Criar repro sintetico com mocks/fixtures.
  • Instrumentar pontos de fronteira para coletar evidencia ate ficar reproduzivel.

3) Coleta de evidencia (sem excesso)

• Ler logs/stack trace/telemetria, buscar mensagens correlatas.
• Checar versoes, flags, configs, variaveis de ambiente.
• Confirmar se e deterministico, intermitente, dependente de rede/timeout/rate limit.

4) Hipoteses explicitas + experimentos

• Escrever H1..Hn (2-5 hipoteses) ordenadas por probabilidade e custo de teste.
• Para cada hipotese: experimento para falsificar e o resultado esperado.
• Evitar mudancas de codigo antes de ter uma hipotese testada, exceto instrumentacao minima.

5) Instrumentacao (quando necessario)

Se faltam logs/visibilidade:

• Inserir logs temporarios nos pontos de fronteira:
  • Entrada: parametros, IDs, versao, feature flags (sem vazar segredos).
  • Saida: status, tempos, erro normalizado.
• Incluir correlacao (requestId/traceId) e medir latencia.
• Guardar por flag (DEBUG=true) e remover apos diagnostico.

6) Encontrar a causa raiz (cadeia causal)

• Descrever a cadeia completa: input -> validacao -> transformacao -> chamada externa -> persistencia/cache -> retorno/efeito colateral.
• Checar "outras origens":
  • Outros callers do mesmo metodo
  • Paths alternativos (if/feature flags)
  • Diferenca entre ambientes (prod/stage/dev)
  • Cache, retries, timeouts, rate limits
  • Concorrencia/ordenacao (race conditions)

7) Implementar o fix

• Corrigir na causa raiz.
• Preferir mudancas pequenas, localizadas, com nomes claros e comentarios minimos (somente o necessario).
• Se envolver instabilidade de rede/external API:
  • retries com backoff (se idempotente), timeouts, circuit-breaker simples, e mensagens de erro uteis.

8) Validar (obrigatorio)

• Confirmar:
  • Repro original agora passa.
  • Teste novo cobre o bug (falha antes, passa depois).
  • Suites relevantes passam (unit/integration/e2e/lint/build).