systematic-debugging

Visão geral da skill systematic-debugging

A skill systematic-debugging é um fluxo estruturado de depuração para agentes e desenvolvedores que querem menos correções no chute e mais rapidez para chegar à causa raiz. A regra central é simples: investigue antes de mudar o código. Por isso, ela é uma ótima escolha para falhas de teste, comportamento intermitente, bugs em produção, problemas de build e falhas de integração em que um “quick fix” tende a esconder o problema real.

Para quem essa skill systematic-debugging é mais indicada

Use systematic-debugging se você:

• está vendo correções falharem repetidamente ou resolverem só parte do problema
• precisa depurar sob pressão de tempo
• quer que um assistente de IA desacelere e investigue, em vez de só remendar sintomas
• busca um processo repetível para bugs, testes flaky e comportamentos inesperados

Ela é especialmente útil quando o problema parece óbvio, mas você ainda não sabe por que acontece.

Qual trabalho essa skill realmente ajuda a fazer

O trabalho real não é “produzir uma correção”. É:

1. reproduzir o problema,
2. rastrear a causa,
3. testar uma explicação por vez,
4. só então implementar uma correção direcionada.

Parece mais lento, mas normalmente reduz retrabalho, patches que falham e bugs novos introduzidos por tentativa e erro.

O que diferencia a systematic-debugging

A maioria dos prompts comuns pula do sintoma para a solução. A systematic-debugging skill parte do princípio de que isso não deve acontecer. O repositório enfatiza um fluxo no estilo “Iron Law”: nada de correções sem antes investigar a causa raiz.

Os arquivos ao redor também tornam a skill mais prática do que uma checklist genérica de debugging:

• root-cause-tracing.md ajuda quando o erro visível está longe da origem real
• condition-based-waiting.md ajuda com testes assíncronos flaky causados por atrasos arbitrários
• defense-in-depth.md ajuda a transformar uma correção pontual de validação em prevenção estrutural
• find-polluter.sh ajuda a isolar testes que deixam arquivos ou estado “vazando”

Tipos de problema em que a systematic-debugging encaixa melhor

systematic-debugging for Debugging funciona muito bem para:

• testes falhando sem uma explicação clara ainda
• testes flaky no CI
• bugs em que correções anteriores não resolveram de verdade
• erros que aparecem em partes profundas da stack
• estado inválido, arquivos deixados para trás, paths errados, race conditions e problemas de timing

Quando essa skill systematic-debugging é uma escolha fraca

Só vale pular a skill quando a tarefa não é realmente debugging, como:

• desenvolvimento direto de funcionalidade
• refactors rotineiros sem comportamento falhando para explicar
• mudanças puramente cosméticas

Ainda assim, se você está reagindo a “comportamento inesperado”, systematic-debugging quase sempre é o ponto de partida mais seguro.

Como usar a skill systematic-debugging

Contexto de instalação da systematic-debugging

Se você usa o padrão Skills CLI adotado neste ecossistema, instale com:

npx skills add https://github.com/obra/superpowers --skill systematic-debugging

Depois, invoque a skill no ambiente do seu agente ou siga o processo manualmente lendo os arquivos-fonte na pasta da skill.

Leia estes arquivos primeiro

Para um systematic-debugging guide rápido e com alta densidade de sinal, leia nesta ordem:

1. skills/systematic-debugging/SKILL.md
2. skills/systematic-debugging/root-cause-tracing.md
3. skills/systematic-debugging/condition-based-waiting.md
4. skills/systematic-debugging/defense-in-depth.md
5. skills/systematic-debugging/find-polluter.sh

Por que nessa ordem:

• SKILL.md traz o fluxo obrigatório de quatro fases
• root-cause-tracing.md ajuda quando os sintomas aparecem muito depois da origem
• condition-based-waiting.md oferece um padrão concreto de correção para testes assíncronos flaky
• defense-in-depth.md ajuda a tornar a correção final mais robusta
• find-polluter.sh é um isolador prático para poluição entre testes

Quais entradas a skill systematic-debugging precisa de você

A qualidade do systematic-debugging usage depende muito do que você fornece. Entregue para a skill:

• mensagem de erro exata
• stack trace
• passos de reprodução
• comportamento esperado vs. comportamento real
• detalhes do ambiente, como OS, runtime, test runner, CI-only ou local-only
• mudanças recentes no código
• se o problema é determinístico ou flaky
• o que você já tentou

Sem isso, o modelo tende muito mais a especular.

Como transformar um bug report raso em um prompt forte

Prompt fraco:

Test is failing. Help fix it.

Prompt melhor:

Use systematic-debugging on this failing test. Do not propose a fix until root cause investigation is complete. Here is the exact error, stack trace, reproduction command, recent changes, and the one behavior difference between local and CI. Identify likely root causes, suggest the minimum investigation steps, and keep hypotheses separate.

Esse prompt funciona melhor porque pede saída de investigação antes da implementação.

Um template de prompt prático

Use esta estrutura para systematic-debugging usage:

• Problema: o que falhou
• Reprodução: comando exato ou passos
• Evidências: logs, trace, screenshots, assertion que falhou
• Escopo: local, CI, uma máquina, todos os ambientes
• Mudanças recentes: commits, atualizações de dependência, edições de configuração
• Restrições: não pode mudar a API, precisa de patch mínimo, prazo etc.
• Pedido: investigar a causa raiz primeiro, depois propor uma correção

Exemplo:

Use systematic-debugging for this Jest failure. Repro: npm test src/foo.test.ts. Error: Timeout waiting for TOOL_RESULT event after 5000ms. It fails in CI and under parallel runs, not always locally. We recently changed thread event handling. First investigate root cause, then propose one focused fix and one validation plan.

Siga o fluxo de quatro fases na ordem

O repositório gira em torno de quatro fases. Na prática, use assim:

1. Investigação da causa raiz
   Leia o erro com atenção, reproduza com confiabilidade, inspecione o que mudou e reúna evidências.
2. Análise de padrões
   Procure padrões de timing, ambiente, formato de entrada, vazamento de estado ou cadeia de chamadas.
3. Teste de hipóteses
   Formule uma explicação por vez e teste essa explicação. Evite mudar várias variáveis ao mesmo tempo.
4. Implementação
   Só depois de haver evidências para sustentar a causa, faça a correção e valide.

Se a Fase 1 for fraca, todas as etapas seguintes pioram.

Como usar systematic-debugging em testes flaky

Este repositório ajuda de forma incomumente prática nesse caso. Se um teste depende de sleep, setTimeout ou esperas arbitrárias, examine condition-based-waiting.md e condition-based-waiting-example.ts.

A mudança principal é:

• padrão ruim: chutar quanto tempo o trabalho assíncrono leva
• padrão melhor: esperar pela condição que comprova a conclusão

Isso importa porque muitas falhas “aleatórias” são, na verdade, race conditions escondidas por suposições de timing.

Como usar a systematic-debugging quando o sintoma aparece a jusante

Se o erro aparece no fundo da stack ou longe de onde os dados incorretos surgiram, use root-cause-tracing.md. O fluxo é:

• identificar a linha que falha imediatamente
• subir um chamador na cadeia
• continuar rastreando até encontrar onde o estado errado apareceu pela primeira vez
• corrigir na origem, não só no ponto do crash

Essa é uma das partes mais valiosas da systematic-debugging skill, porque muitos bugs são apenas sintomas de um estado inválido anterior.

Como usar o localizador de polluter

Para testes que deixam arquivos, diretórios ou estado para trás, vale a pena ler find-polluter.sh antes de improvisar seu próprio loop.

Padrão de uso:
./find-polluter.sh <file_or_dir_to_check> <test_pattern>

Exemplo do script:
./find-polluter.sh '.git' 'src/**/*.test.ts'

Isso é útil quando a falha é causada por poluição oculta entre testes, e não pelo teste que aparentemente falhou.

Fluxo comum que traz os melhores resultados

Um fluxo confiável para systematic-debugging install e primeiro uso:

1. instale a skill
2. leia SKILL.md
3. colete evidências exatas da falha
4. peça ao agente para investigar sem corrigir
5. escolha a hipótese mais sustentada por evidências
6. teste somente essa hipótese
7. implemente uma correção focada
8. adicione validação ou defense-in-depth se o bug veio de dados inválidos ou de múltiplos caminhos de entrada

Isso evita o modo de falha mais comum: mudar código antes de entender o problema.

O que não fazer com esta skill systematic-debugging

Não peça para systematic-debugging:

• listar muitas correções imediatamente
• reescrever áreas grandes antes de reproduzir o bug
• “só fazer o teste passar” sem explicação
• corrigir várias causas suspeitas ao mesmo tempo

Esses atalhos entram em conflito direto com o desenho da skill e reduzem a qualidade da resposta.

FAQ da skill systematic-debugging

A systematic-debugging serve só para bugs complexos?

Não. A posição do repositório é que mesmo bugs simples têm causas raiz. A skill é mais valiosa justamente quando o problema parece simples o bastante para convidar um patch rápido.

Em que isso é diferente de um prompt normal de debugging?

Um prompt comum costuma premiar velocidade e correções especulativas. systematic-debugging força o modelo a separar investigação, hipótese e implementação. Isso normalmente produz menos patches errados e explicações melhores.

A systematic-debugging é amigável para iniciantes?

Sim, desde que você consiga fornecer evidências concretas. O processo é rigoroso, mas os passos são claros: reproduzir, inspecionar, rastrear, testar uma ideia e depois corrigir. Iniciantes podem até se beneficiar mais, porque a skill evita tentativa e erro aleatória.

Quando eu não deveria usar systematic-debugging?

Não use como padrão principal para:

• ideação de funcionalidades
• brainstorming de arquitetura
• geração de código sem relação com uma falha
• ajustes puramente visuais sem comportamento quebrado para explicar

Use quando algo está errado e você precisa da causa, não só de um patch.

A systematic-debugging ajuda com falhas que só acontecem no CI?

Sim. Ela é muito adequada para falhas que só aparecem no CI ou sob carga, porque força você a comparar ambientes, reproduzir condições e inspecionar suposições sobre timing e estado, em vez de adivinhar.

Ela pode ajudar com testes assíncronos flaky?

Sim, e este repositório é melhor do que a média nesse ponto. condition-based-waiting.md e o arquivo de exemplo em TypeScript mostram um caminho concreto para sair de esperas arbitrárias e migrar para sincronização baseada em condição.

A skill inclui tooling ou só orientação?

Principalmente orientação de processo, com alguns arquivos complementares concretos. O helper mais prático é find-polluter.sh, e o exemplo de espera baseada em condição pode ser reaproveitado diretamente em alguns setups de teste com TypeScript.

Posso usar systematic-debugging com qualquer stack?

Na maior parte dos casos, sim. O método central independe de stack. Os exemplos se inclinam mais para TypeScript, shell e fluxos de teste, mas o processo de investigação funciona em várias linguagens e frameworks.

Como melhorar a skill systematic-debugging

Forneça evidências melhores antes de pedir uma correção

A maior alavanca está na qualidade da entrada. Para obter resultados melhores com systematic-debugging, inclua:

• um comando exato de reprodução
• um bloco exato de erro
• um teste ou arquivo mínimo que falha
• o que mudou recentemente
• se o problema é sempre reproduzível

Isso ajuda a skill a trabalhar com evidências, e não com inferência.

Peça saída de investigação antes da implementação

Um prompt de alto desempenho bloqueia explicitamente correções prematuras. Por exemplo:

Use systematic-debugging. First produce root-cause investigation findings and the top 2 hypotheses with evidence for each. Do not suggest code changes yet.

Isso melhora a qualidade da resposta porque cria um checkpoint entre a leitura do sintoma e a edição do código.

Force uma hipótese por vez

Um modo de falha comum é misturar várias causas possíveis em um único patch. Peça:

• a hipótese principal
• o menor teste capaz de refutá-la
• qual resultado a confirmaria

Isso mantém o fluxo alinhado com a intenção da skill.

Melhore os prompts para cenários de teste flaky

Ao usar systematic-debugging for Debugging em testes flaky, informe:

• frequência de sucesso/falha
• se as falhas têm relação com paralelismo ou CI
• qualquer uso de sleeps, waits, retries ou polling
• o evento ou estado exato que o teste está tentando observar

Isso facilita muito para o modelo reconhecer quando condition-based-waiting.md é o padrão complementar relevante.

Use os arquivos próximos do código-fonte, não só o SKILL.md

Se a primeira resposta parecer genérica, aponte o modelo para a documentação de apoio:

• root-cause-tracing.md para sintomas que aparecem a jusante
• condition-based-waiting.md para problemas de timing/race
• defense-in-depth.md para estratégia de validação
• find-polluter.sh para poluição entre testes

A skill fica melhor quando o agente usa o material complementar especializado, não só o fluxo principal.

Reduza o escopo depois da primeira passada

Se o primeiro resultado vier amplo demais, refine com:

• o subsistema exato a inspecionar
• a fronteira suspeita por onde entram os dados incorretos
• o primeiro commit em que o problema apareceu
• a menor reprodução que falha

Prompts amplos de debugging costumam gerar planos amplos de debugging. Escopo estreito produz um trabalho melhor de causa raiz.

Melhore a correção final, não só o diagnóstico

Depois de encontrar a causa raiz, peça:

• a correção mínima
• um teste de regressão
• uma camada de validação que evite recorrência

É aqui que defense-in-depth.md se torna útil. Se o bug veio de entradas inválidas ou de suposições que podem ser contornadas, um único patch pode não bastar.

Fique atento a estes modos de falha comuns

Um systematic-debugging usage ruim geralmente vem de:

• texto de erro incompleto
• ausência de reprodução confiável
• pedir correções cedo demais
• mudar várias coisas entre execuções de teste
• tratar a primeira explicação plausível como se estivesse provada

Se você evitar isso, a skill se torna muito mais valiosa do que um prompt genérico de “debug this”.