AgentDock - Análise Profunda de Bugs

Quebre o Ciclo - Análise Profunda de Bugs

Quando a depuração estiver concluída, use isto para uma análise profunda e quebrar o ciclo "corrigir bug -> esquecer -> repetir".

---

Framework de Análise

Analise o bug que você acabou de corrigir sob estas 5 dimensões:

1. Categoria da Causa Raiz

A qual categoria este bug pertence?

Categoria	Características	Exemplo
A. Especificação Ausente	Nenhuma documentação sobre como fazer	Novo recurso sem checklist
B. Contrato entre Camadas	Interface entre camadas pouco clara	API retorna formato diferente do esperado
C. Falha na Propagação de Mudanças	Mudou um lugar, esqueceu outros	Alterou assinatura de função, esqueceu locais de chamada
D. Lacuna na Cobertura de Testes	Teste unitário passa, integração falha	Funciona isoladamente, quebra quando combinado
E. Suposição Implícita	Código depende de suposição não documentada	Segundos vs milissegundos em timestamp

2. Por que as Correções Falharam (se aplicável)

Se você tentou várias correções antes de ter sucesso, analise cada falha:

• Correção Superficial: Corrigiu o sintoma, não a causa raiz
• Escopo Incompleto: Encontrou a causa raiz, mas não cobriu todos os casos
• Limitação da Ferramenta: O grep não encontrou, a verificação de tipo não era rigorosa
• Modelo Mental: Continuou procurando na mesma camada, não pensou entre camadas

3. Mecanismos de Prevenção

Quais mecanismos impediriam que isso acontecesse novamente?

Tipo	Descrição	Exemplo
Documentação	Escreva para que as pessoas saibam	Atualizar guia de pensamento
Arquitetura	Torne o erro estruturalmente impossível	Wrappers type-safe
Tempo de Compilação	Verificação de tipo rigorosa, sem escapes	Mudança de assinatura causa erro de compilação
Tempo de Execução	Monitoramento, alertas, varreduras	Detectar entidades órfãs
Cobertura de Testes	Testes E2E, testes de integração	Verificar fluxo completo
Revisão de Código	Checklist, template de PR	"Você verificou X?"

4. Expansão Sistemática

Que problemas mais amplos este bug revela?

• Problemas Semelhantes: Onde mais esse problema pode existir?
• Falha de Design: Existe um problema fundamental de arquitetura?
• Falha de Processo: Existe uma melhoria no processo de desenvolvimento?
• Lacuna de Conhecimento: A equipe está perdendo algum entendimento?

5. Captura de Conhecimento

Solidifique os insights no sistema:

• Atualizar guias de pensamento em .trellis/spec/guides/
• Atualizar documentos relevantes em .trellis/spec/
• Criar registro de issue (se aplicável)
• Criar ticket de recurso para correção raiz
• Atualizar diretrizes de verificação, se necessário

---

Formato de Saída

Por favor, produza a análise neste formato:

## Análise de Bug: [Descrição Curta]

### 1. Categoria da Causa Raiz
- **Categoria**: [A/B/C/D/E] - [Nome da Categoria]
- **Causa Específica**: [Descrição detalhada]

### 2. Por que as Correções Falharam (se aplicável)
1. [Primeira tentativa]: [Por que falhou]
2. [Segunda tentativa]: [Por que falhou]
...

### 3. Mecanismos de Prevenção
| Prioridade | Mecanismo | Ação Específica | Status |
|------------|-----------|-----------------|--------|
| P0 | ... | ... | TODO/DONE |

### 4. Expansão Sistemática
- **Problemas Semelhantes**: [Liste locais com problemas semelhantes]
- **Melhoria de Design**: [Sugestões a nível de arquitetura]
- **Melhoria de Processo**: [Sugestões de processo de desenvolvimento]

### 5. Captura de Conhecimento
- [ ] [Documentos a atualizar / tickets a criar]

---

Filosofia Central

O valor da depuração não está em corrigir o bug, mas em fazer com que esta classe de bugs nunca mais aconteça.

Três níveis de insight:

1. Tático: Como corrigir ESTE bug
2. Estratégico: Como prevenir ESTA CLASSE de bugs
3. Filosófico: Como expandir padrões de pensamento

30 minutos de análise economizam 30 horas de depuração futura.

Framework de Pensamento: Raciocínio Bayesiano

Quando múltiplas causas raiz são plausíveis e a evidência é incompleta, atualize suas crenças proporcionalmente a novas evidências, em vez de se agarrar a suposições iniciais.

Passo 1: Estabeleça Priores

Antes de investigar, declare o que você acredita e por quê:

Hipótese	Prior	Raciocínio
H1: [causa A]	40%	Mais comum para este padrão
H2: [causa B]	30%	Plausível dado o ambiente
H3: [outro]	30%	Captura geral

Os priores devem somar 100%. Se você não consegue atribuir probabilidades, investigue primeiro.

Passo 2: Observe a Evidência

Documente o que você encontrou — seja específico sobre a confiabilidade:

• O que exatamente você observou?
• Quão confiável? (saída de teste > mensagem de log > relatório de usuário > palpite)
• Múltiplas hipóteses poderiam explicar isso?

Passo 3: Atualize as Crenças

Para cada hipótese, pergunte: Qual a probabilidade desta evidência se esta hipótese fosse verdadeira?

A direção da atualização importa mais do que o cálculo:

• Evidência fortemente prevista por H1 → Probabilidade de H1 aumenta
• Evidência contradiz H2 → Probabilidade de H2 diminui
• Evidência igualmente provável sob todas → nenhuma atualização

Passo 4: Busque Evidência Discriminatória

Não colete mais do mesmo. Encontre evidência que difere fortemente entre as principais hipóteses.

Se H1 e H3 estão próximas: "O que eu veria se H1 for verdadeira, mas não se H3 for verdadeira?" Em seguida, verifique isso.

Passo 5: Declare a Confiança

Confiança	Ação
90%+	Prossiga com a correção, monitore
70-90%	Prossiga, adicione verificação de fallback
50-70%	Teste a hipótese antes de se comprometer
<50%	Precisa de mais evidência, não chute

Nunca expresse certeza binária quando a evidência é incompleta. Use "muito provável", "plausível mas improvável", "vale a pena investigar".

Falácias Comuns

Falácia	Exemplo	Correção
Negligência da taxa base	"Teste falhou → código está quebrado"	Com que frequência os testes falham por outros motivos?
Viés de confirmação	"Deve ser uma condição de corrida, deixe-me encontrar evidência de corrida"	Busque ativamente evidência CONTRA sua hipótese principal
Ancoragem	"Da última vez foi cache, provavelmente é cache de novo"	Estabeleça priores a partir do contexto atual, não do bug de ontem

---

Após a Análise: Ações Imediatas

IMPORTANTE: Após concluir a análise acima, você DEVE imediatamente:

1. Atualizar spec/guides - Não apenas liste TODOs, realmente atualize os arquivos relevantes:

   • Se for um problema entre plataformas → atualize cross-platform-thinking-guide.md
   • Se for um problema entre camadas → atualize cross-layer-thinking-guide.md
   • Se for um problema de reutilização de código → atualize code-reuse-thinking-guide.md
   • Se for específico de domínio → atualize backend/*.md ou frontend/*.md

2. Sincronizar templates - Após atualizar .trellis/spec/, sincronize com src/templates/markdown/spec/

3. Commite as atualizações de spec - Esta é a saída principal, não apenas o texto da análise

A análise é inútil se ficar no chat. O valor está nas specs atualizadas.