parallel-debugging

Visão geral da skill parallel-debugging

O que a parallel-debugging faz

A parallel-debugging é uma workflow estruturada de depuração para casos em que um bug tem várias causas plausíveis e uma investigação linear comum continua emperrando. Em vez de perseguir uma única teoria, ela usa hipóteses concorrentes, investigação em paralelo, coleta de evidências e arbitragem explícita para decidir qual é a causa raiz mais provável.

Quem deve instalar esta skill

A parallel-debugging skill faz mais sentido para desenvolvedores, agentes de IA e equipes que depuram com frequência falhas confusas que atravessam arquivos, serviços ou camadas. Ela é especialmente útil quando os sintomas são reais, mas a causa não está clara, quando tentativas anteriores de depuração foram inconclusivas ou quando há risco de viés de confirmação.

Melhor trabalho a ser resolvido

Use parallel-debugging for Debugging quando você precisa responder: “Qual é a causa raiz mais defensável, com base em evidências?” O valor real não está só em levantar possíveis causas. Está em transformar um relato vago de bug em hipóteses falseáveis, investigações com escopo definido, evidências no nível de arquivo e um veredito fundamentado.

O que diferencia esta skill de um prompt genérico de debugging

A maioria dos prompts comuns pede ao modelo para “encontrar o bug”, o que muitas vezes leva a um único palpite plausível. A parallel-debugging é mais forte quando várias causas podem explicar o mesmo sintoma. A skill força a investigação a cobrir categorias de falha, exige evidências de confirmação e de refutação e usa uma etapa de arbitragem, em vez de tratar a primeira explicação razoável como verdade.

Método central exposto pelo repositório

O repositório se apoia na abordagem Analysis of Competing Hypotheses e organiza a depuração em seis categorias de falha: erro de lógica, problema de dados, problema de estado, falha de integração, problema de recurso e ambiente. Essa categorização é prática porque amplia a cobertura da busca sem deixá-la aberta demais.

Quando esta skill não é uma boa escolha

Evite parallel-debugging usage em bugs simples e locais, quando a linha com falha já está evidente, em erros de sintaxe rotineiros ou quando você só precisa de uma sugestão rápida de patch. O método adiciona overhead, então compensa principalmente quando o problema é a incerteza.

Como usar a skill parallel-debugging

Contexto de instalação da parallel-debugging

Instale a partir do repositório wshobson/agents:

npx skills add https://github.com/wshobson/agents --skill parallel-debugging

Se o seu ambiente usa outro carregador de skills, o ponto importante é o caminho de origem: plugins/agent-teams/skills/parallel-debugging.

Leia estes arquivos primeiro, antes do primeiro uso

Comece por:

• SKILL.md
• references/hypothesis-testing.md

O SKILL.md traz o workflow e o enquadramento por modos de falha. O references/hypothesis-testing.md é o arquivo mais valioso na execução prática, porque contém templates de investigação e de relatório de evidências que você pode reutilizar diretamente.

Que tipo de entrada a skill precisa para funcionar bem

Para obter um bom parallel-debugging usage, forneça mais do que “X quebrou”. A skill funciona melhor quando você informa:

• sintoma observado
• comportamento esperado
• contexto de mudança recente ou deploy
• arquivos, módulos ou serviços afetados
• passos de reprodução
• logs, stack traces ou testes falhando
• restrições sobre o que o agente pode inspecionar ou executar

Sem isso, o modelo ainda consegue gerar hipóteses, mas a investigação tende a ficar genérica e menos falseável.

Como transformar um relato vago de bug em uma invocação forte

Entrada fraca:

• “Login is failing in production. Debug this.”

Entrada mais forte:

• “Investigate intermittent login failures after yesterday’s auth middleware change. Symptom: users with valid credentials sometimes get 401 on first attempt but succeed on retry. Check src/middleware/auth.ts, session cache behavior, recent commits from the last 3 days, and tests under tests/auth/. Generate competing hypotheses, collect confirming and falsifying evidence, and rank the most likely root cause.”

A segunda versão dá a forma do sintoma, a janela de tempo, as superfícies mais prováveis e os limites da evidência.

Use a skill parallel-debugging como um workflow em etapas

Um parallel-debugging guide prático se parece com isto:

1. Declare o sintoma e o escopo.
2. Peça de 3 a 5 hipóteses concorrentes em categorias de falha diferentes.
3. Para cada hipótese, defina evidências que a confirmem e que a refutem.
4. Investigue em paralelo ou simule trilhas paralelas em uma única resposta.
5. Compare a qualidade da evidência, não apenas a plausibilidade.
6. Termine com um veredito ranqueado, nível de confiança e próxima ação.

Este é o principal benefício de adoção: evitar convergência prematura.

Peça evidências file:line, não resumos

O template de referência espera explicitamente citações de arquivo e cadeias causais. Na prática, exija:

• evidência file:line
• evidência de contradição
• nível de confiança
• correção recomendada só depois do veredito

Essa ordem importa. Se você pedir correções cedo demais, o modelo tende a otimizar para escrever um patch antes de ter segurança sobre a causa raiz.

Use os seis modos de falha para ampliar a busca com critério

Se a primeira lista de hipóteses vier estreita demais, peça ao modelo para cobrir todas as categorias definidas no repositório: