bugfix

Skill de Bugfix

Filosofia

Um bugfix segue as mesmas 3 fases do workflow, mas comprimidas:

• Investigar (pesquisa): entender o bug antes de tocar no código
• Diagnosticar (discussão): confirmar a causa raiz com o humano
• Corrigir (execução): fix cirúrgico + teste + commit detalhado

Processo

Fase 1: Investigar (NÃO toque no código ainda)

1. Reproduzir: Entenda como o bug se manifesta

   • Qual o comportamento esperado?
   • Qual o comportamento atual?
   • Há mensagem de erro ou stack trace?

2. Rastrear: Delegue ao subagent scout se necessário

   • Grep pelo erro/mensagem no codebase
   • Trace o fluxo de dados do input até onde quebra
   • Identifique os arquivos envolvidos
   • Verifique se há testes existentes que deveriam ter pego isso

3. Contextualizar:

   • Quando começou? (git log/blame pode ajudar)
   • Outros lugares têm o mesmo padrão e podem ter o mesmo bug?
   • Há issues relacionadas conhecidas em KNOWLEDGE.md?

Fase 2: Diagnosticar (confirmar antes de corrigir)

Apresente ao humano:

🐛 DIAGNÓSTICO

Bug: [descrição curta]
Severidade: crítica / alta / média / baixa

📍 Causa raiz:
[Explicação clara do que está causando o bug]

📁 Arquivos afetados:
- [arquivo1.ts] — [o que está errado neste arquivo]
- [arquivo2.ts] — [o que está errado neste arquivo]

🔧 Correção proposta:
[Descrição do que será feito — sem código, apenas a abordagem]

💥 Impacto da correção:
- [O que muda]
- [O que pode quebrar]
- [Outros lugares que podem precisar do mesmo fix]

Confirma a correção? Quer ajustar a abordagem?

Aguarde confirmação do humano antes de prosseguir.

Fase 3: Corrigir

1. Fix cirúrgico: Altere APENAS o necessário para corrigir o bug

   • Não refatore código adjacente (a menos que o humano peça)
   • Não "melhore" coisas que não estão quebradas
   • Foco: resolver a causa raiz, não os sintomas

2. Adicionar teste de regressão:

   • Escreva um teste que FALHA sem o fix e PASSA com o fix
   • O teste deve cobrir exatamente o cenário do bug
   • Se possível, adicione edge cases relacionados

3. Verificar:

   • Rode o teste de regressão: deve passar
   • Rode a suite completa: nada deve ter quebrado
   • Se o bug era visual, descreva como verificar manualmente

4. Verificar blast radius:

   • Grep por padrões similares ao código corrigido
   • Se o mesmo padrão bugado existe em outros lugares, liste-os
   • Pergunte ao humano se quer corrigir os outros agora ou criar tasks separadas

Fase 4: Documentar e Commitar

1. Criar commit detalhado:

git add .
git commit -m "fix(escopo): [descrição curta do bug]

Problema:
[Descrição do que estava acontecendo — 2-3 linhas]

Causa raiz:
[O que estava causando — 1-2 linhas]

Correção:
[O que foi feito para resolver — lista dos pontos principais]

Teste de regressão:
[Nome do teste adicionado e o que ele verifica]

Arquivos alterados:
- [arquivo1.ts] — [o que mudou]
- [arquivo2.ts] — [o que mudou]

Refs: [#issue se houver]"

2. Atualizar KNOWLEDGE.md se o bug revela um padrão que pode se repetir:

## Bug: [Título curto]
- **Data:** YYYY-MM-DD
- **Sintoma:** [O que o usuário vê]
- **Causa:** [O que estava errado]
- **Lição:** [Como evitar no futuro]

3. Reportar ao humano:

✅ BUG CORRIGIDO

🐛 Bug: [descrição]
📁 Arquivos alterados: X
🧪 Teste de regressão: [nome do teste]
📝 Commit: [hash curto] — fix(escopo): [descrição]

⚠️  Atenção:
[Padrões similares encontrados em outros lugares, se houver]

Regras

• NUNCA corrija sem diagnosticar primeiro
• NUNCA corrija sem confirmação do humano
• Fix cirúrgico: mínimo de mudanças necessárias
• SEMPRE adicione teste de regressão
• Commit message deve contar a história completa do bug
• Se descobrir outros bugs durante a investigação, registre separadamente