O que Triagem de Issue faz?
Investigue um problema relatado, encontre sua causa raiz e crie uma issue no GitHub com um plano de correção TDD. Este é um fluxo de trabalho principalmente sem intervenção - minimize perguntas ao usuário.
Processo
1. Capture o problema
Obtenha uma breve descrição do problema do usuário. Se ele não forneceu uma, faça UMA pergunta: "Qual problema você está vendo?"
NÃO faça perguntas de acompanhamento ainda. Comece a investigar imediatamente.
2. Explore e diagnostique
Use a ferramenta Agent com subagent_type=Explore para investigar profundamente o código. Seu objetivo é encontrar:
- Onde o bug se manifesta (pontos de entrada, UI, respostas de API)
- Qual caminho de código está envolvido (trace o fluxo)
- Por que ele falha (a causa raiz, não apenas o sintoma)
- Qual código relacionado existe (padrões semelhantes, testes, módulos adjacentes)
Analise:
- Arquivos de origem relacionados e suas dependências
- Testes existentes (o que é testado, o que está faltando)
- Mudanças recentes em arquivos afetados (
git lognos arquivos relevantes) - Tratamento de erros no caminho do código
- Padrões semelhantes em outras partes do código que funcionam corretamente
3. Identifique a abordagem de correção
Com base em sua investigação, determine:
- A mudança mínima necessária para corrigir a causa raiz
- Quais módulos/interfaces são afetados
- Quais comportamentos precisam ser verificados por meio de testes
- Se isso é uma regressão, funcionalidade ausente ou falha de design
4. Projete o plano de correção TDD
Crie uma lista concreta e ordenada de ciclos RED-GREEN. Cada ciclo é uma fatia vertical:
- RED: Descreva um teste específico que captura o comportamento quebrado/ausente
- GREEN: Descreva a mudança mínima de código para fazer esse teste passar
Regras:
- Testes verificam comportamentos por meio de interfaces públicas, não detalhes de implementação
- Um teste de cada vez, fatias verticais (NÃO todos os testes primeiro, depois todo o código)
- Cada teste deve sobreviver a refatorações internas
- Inclua uma etapa de refatoração final, se necessário
- Durabilidade: Sugira apenas correções que sobreviveriam a mudanças radicais no código. Descreva comportamentos e contratos, não estrutura interna. Testes devem afirmar resultados observáveis (respostas de API, estado da UI, efeitos visíveis ao usuário), não estado interno. Uma boa sugestão parece uma especificação; uma má sugestão parece um diff.
5. Crie a issue no GitHub
Crie uma issue no GitHub usando gh issue create com o modelo abaixo. NÃO peça ao usuário para revisar antes de criar - apenas crie e compartilhe o URL.
Problema
Uma descrição clara do bug ou problema, incluindo:
- O que acontece (comportamento real)
- O que deveria acontecer (comportamento esperado)
- Como reproduzir (se aplicável)
Análise de Causa Raiz
Descreva o que você encontrou durante a investigação:
- O caminho de código envolvido
- Por que o código atual falha
- Quaisquer fatores contribuintes
NÃO inclua caminhos de arquivo específicos, números de linha ou detalhes de implementação que estejam vinculados ao layout atual do código. Descreva módulos, comportamentos e contratos. A issue deve permanecer útil mesmo após grandes refatorações.
Plano de Correção TDD
Uma lista numerada de ciclos RED-GREEN:
-
RED: Escreva um teste que [descreve o comportamento esperado] GREEN: [Mudança mínima para fazê-lo passar]
-
RED: Escreva um teste que [descreve o próximo comportamento] GREEN: [Mudança mínima para fazê-lo passar]
...
REFACTOR: [Qualquer limpeza necessária após todos os testes passarem]
Critérios de Aceitação
- Critério 1
- Critério 2
- Todos os novos testes passam
- Testes existentes ainda passam
Após criar a issue, imprima o URL da issue e um resumo de uma linha da causa raiz.