Bug Hunt Swarm

Quando Usar

Use esta habilidade quando precisar de investigação de causa raiz multi-agente em leitura paralela para bugs, regressões, travamentos, comportamento instável ou falhas inexplicáveis. Use quando o usuário pedir para investigar um bug, encontrar a causa raiz, rastrear uma regressão, entender por que algo quebrou, ou quiser um diagnóstico classificado com o...

Investigue um bug com quatro sub-agentes de leitura paralela, e então peça ao agente principal para classificar as causas prováveis e recomendar o caminho mais rápido para provar ou corrigir o problema. Esta habilidade é focada em diagnóstico: não edite arquivos ou implemente correções como parte deste fluxo de trabalho.

Passo 1: Construir o Pacote do Bug

Comece coletando o menor pacote de investigação útil:

1. Sintoma
2. Comportamento esperado
3. Comportamento real
4. Passos de reprodução, se conhecidos
5. Escopo do impacto
6. Evidências relevantes, como logs, rastros de pilha (stack traces), testes falhando, capturas de tela, diffs recentes ou detalhes do ambiente

Prefira esta ordem de origem:

1. Descrição direta do usuário
2. Arquivos explícitos, rastros de pilha, logs, testes ou capturas de tela fornecidos pelo usuário
3. Alterações atuais do git ou histórico recente do repositório quando o bug parecer uma regressão
4. O menor caminho de código ou subsistema relevante em torno da falha

Se o relatório de bug for subespecificado, infira uma declaração mínima do problema e diga o que ainda é desconhecido.

Antes de lançar os sub-agentes, leia as instruções do projeto mais próximas e a documentação relevante para a área tocada, como:

• AGENTS.md
• documentação do fluxo de trabalho do repositório
• documentação de arquitetura, estado, roteamento, esquema ou tempo de execução para o subsistema afetado

Passo 2: Delimitar a Investigação

Escreva um breve resumo da investigação para o enxame (swarm):

1. O que parece quebrado
2. O que ainda não foi provado
3. Que parte do sistema está mais provavelmente envolvida
4. Que evidências já existem
5. Que tipo de prova contaria como confirmação

Use coleta de evidências em modo de leitura onde for útil:

• rg, git diff, git log, git show
• leitura de logs, rastros de travamento e configurações
• execuções de teste existentes ou o menor comando de reprodução seguro

Não edite arquivos, injete nova instrumentação ou implemente correções como parte desta habilidade.

Passo 3: Lançar Quatro Investigadores em Leitura Paralela

Lance quatro sub-agentes quando o problema for grande ou ambíguo o suficiente para que a investigação paralela ajude. Para um problema minúsculo e óbvio, é aceitável investigar localmente em vez disso.

Para cada sub-agente:

• forneça o mesmo pacote de bug e resumo da investigação
• declare que o sub-agente é somente leitura
• não permita que o sub-agente edite arquivos, execute apply_patch, prepare alterações (stage changes), comite (commit) ou execute qualquer outra ação que modifique o estado
• peça apenas por saída de investigação concisa
• peça por: hipótese, evidências de suporte, evidências ausentes, menor passo de prova e confiança
• diga ao sub-agente para evitar feedback genérico de qualidade de código, detalhes triviais (nits) ou suposições especulativas sem evidências
• diga ao sub-agente para enviar descobertas apenas de volta ao agente principal

Use estas quatro funções de investigação.

Sub-Agente 1: Investigação de Reprodução e Escopo

Esclareça a forma exata da falha e seus limites.

Verifique:

1. O gatilho mais estreito e confiável
2. Condições que fazem o bug aparecer ou desaparecer
3. Comportamento esperado versus real na fronteira da falha
4. Se o impacto é local, transversal (cross-cutting), determinístico ou instável (flaky)

Este sub-agente é somente leitura. Ele não deve editar arquivos, aplicar patches ou fazer quaisquer outras alterações no espaço de trabalho.

Função recomendada para o sub-agente: reviewer

Sub-Agente 2: Investigação de Caminho de Código e Ponto de Falha (Failure Seam)

Rastreie o caminho de execução mais provável e identifique o ponto de falha onde o comportamento diverge.

Verifique:

1. Transições de estado, bordas de ciclo de vida ou problemas de ordenação
2. Suposições incompatíveis entre chamador e chamado
3. Quebras no fluxo de dados ou fluxo de controle
4. A menor região de código mais provavelmente responsável pela falha

Este sub-agente é somente leitura. Ele não deve editar arquivos, aplicar patches ou fazer quaisquer outras alterações no espaço de trabalho.

Função recomendada para o sub-agente: explorer para rastreamento amplo, ou reviewer quando uma análise de raciocínio local mais forte for mais útil

Sub-Agente 3: Investigação de Mudanças Recentes e Regressão

Procure por prováveis regressões no histórico próximo ou em contratos alterados.

Verifique:

1. Diffs recentes que se correlacionam com o sintoma
2. Configuração, flag, dependência, esquema ou desvio de migração
3. Atualizações parciais onde vários pontos de entrada deveriam ter mudado juntos
4. Mudanças de comportamento que se encaixam no momento do relatório do bug

…