systematic-debugging

Visão geral

O que é systematic-debugging?

A skill systematic-debugging é um processo estruturado em quatro fases para depurar qualquer problema técnico: falhas de teste, bugs em produção, testes flaky, problemas de performance, erros de build ou falhas de integração.

Em vez de tentar “um ajuste rápido” ou sair editando o código na primeira linha de erro, esta skill força você a investigar a causa raiz primeiro, para só então desenhar e validar uma correção duradoura. Ela é baseada em padrões práticos e scripts de um código real, incluindo helpers de espera baseada em condição em TypeScript e um script em Bash para encontrar test polluters.

Princípio central e Lei de Ferro

O coração de systematic-debugging é simples:

• Princípio central: Sempre encontre a causa raiz antes de tentar qualquer correção. Correções apenas em cima de sintomas são falhas.

• Lei de Ferro:

  NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
  

Se você não concluiu a fase de investigação, você não propõe nem aplica correções. Isso é projetado para resistir à pressão de tempo, ao achismo e às racionalizações do tipo "só desta vez".

Para quem é esta skill?

systematic-debugging é voltada para:

• Desenvolvedores que trabalham em projetos JavaScript/TypeScript e querem correções confiáveis e reproduzíveis
• Engenheiros de Teste e QA lidando com comportamento flaky, timeouts aleatórios e estado de teste poluído
• Engenheiros de CI/CD e tooling que diagnosticam falhas intermitentes de build ou integração
• Tech leads e revisores que querem um processo compartilhado e rigoroso para trabalhos de depuração

Ela se encaixa melhor em contextos onde você valoriza análise de causa raiz de alta qualidade mais do que remendos rápidos em sintomas.

Que problemas ela resolve?

Use a skill systematic-debugging quando você precisar:

• Investigar falhas de teste que continuam reaparecendo depois das “correções”
• Rastrear testes flaky que dependem de timeouts arbitrários ou condições de corrida
• Entender comportamento inesperado em vez de apenas silenciar erros
• Diagnosticar problemas de performance ou fluxos lentos e sensíveis a tempo
• Depurar falhas de build ou integração que só acontecem no CI ou sob carga
• Descobrir qual teste polui o estado ou deixa arquivos/diretórios indesejados para trás

O repositório também inclui:

• condition-based-waiting.md e condition-based-waiting-example.ts para substituir setTimeout/sleep por esperas robustas baseadas em condição em TypeScript
• defense-in-depth.md para adicionar validação em múltiplas camadas, tornando certos bugs estruturalmente impossíveis
• find-polluter.sh, um helper em Bash para localizar o teste exato que cria arquivos ou estado indesejado
• root-cause-tracing.md para rastrear erros pela cadeia de chamadas até a verdadeira origem

Quando systematic-debugging é uma boa escolha?

systematic-debugging é especialmente indicada quando:

• Você está sob pressão de tempo e tentado a chutar correções
• Um problema continua voltando apesar de várias tentativas anteriores
• Você quer um fluxo de depuração repetível para você ou sua equipe
• Você está estabilizando uma suíte de testes flaky ou limpando ambientes de teste poluídos

Ela pode ser menos adequada se:

• Você só precisa de uma geração de código ou refatoração rápida, pontual, sem investigação
• Você está depurando fora dos domínios técnicos descritos (por exemplo, problemas de processo não técnicos)
• Você não está disposto a seguir um processo passo a passo e prefere experimentação ad hoc

Se o seu objetivo é “remendar rápido agora e aceitar retrabalho depois”, este processo vai parecer rígido. Se o seu objetivo é “corrigir de primeira, do jeito certo”, systematic-debugging foi feita para você.

Como usar

Instalação e configuração

Para instalar a skill systematic-debugging em um agente ou ambiente de ferramentas compatível, use o comando npx fornecido:

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

Esse comando baixa a definição da skill e seus documentos e scripts de suporte a partir do repositório `obra/superpowers`, em `skills/systematic-debugging`.

Após a instalação:

1. Abra a skill `systematic-debugging` no seu agente ou na interface de skills.
2. Garanta que o seu workspace tenha acesso ao repositório do projeto, comandos de teste e logs.
3. Confirme que você consegue ver os guias markdown e scripts incluídos:
   - `SKILL.md`
   - `condition-based-waiting.md`
   - `defense-in-depth.md`
   - `root-cause-tracing.md`
   - `find-polluter.sh`

### Arquivos e componentes importantes
Para decisões de instalação e uso no dia a dia, estes arquivos são os mais relevantes:

- **`SKILL.md`** – Define o processo completo de depuração sistemática em quatro fases, regras e antipadrões. É o núcleo da skill.
- **`condition-based-waiting.md`** – Explica como substituir timeouts arbitrários em testes por espera baseada em condição.
- **`condition-based-waiting-example.ts`** – Utilitários TypeScript como `waitForEvent` que implementam espera baseada em condição com `ThreadManager` e tipos de eventos.
- **`defense-in-depth.md`** – Mostra como aplicar validação em múltiplas camadas (ponto de entrada, lógica de negócio, proteções de ambiente, logging) para tornar classes inteiras de bugs impossíveis.
- **`find-polluter.sh`** – Script em Bash que itera sobre os testes para descobrir qual arquivo cria um determinado path (poluição de estado).
- **`root-cause-tracing.md`** – Explica como rastrear um bug desde o stack trace até o gatilho original, combinando depois com defense-in-depth.
- **`CREATION-LOG.md`** – Um meta-log explicando como o framework foi extraído e fortalecido; útil para entender a intenção de design, menos crítico no uso diário.

Para desenvolvedores **JavaScript/TypeScript**, o exemplo em TypeScript e o script em Bash geralmente podem ser adaptados diretamente ao seu projeto.

### Executando o fluxo de trabalho em quatro fases
O processo de `systematic-debugging` é organizado em quatro fases obrigatórias (descritas em `SKILL.md`). Você deve concluir cada uma antes de passar para a próxima.

#### Fase 1 – Investigação da causa raiz
Antes de tocar em qualquer código, configuração ou teste:

- **Leia as mensagens de erro e os logs com atenção.**
  - Não passe por cima de stack traces ou avisos.
  - Capture números de linha, caminhos de arquivo e códigos de erro.
- **Reproduza o problema de forma consistente.**
  - Estabeleça um comando mínimo e confiável de reprodução.
  - Observe quais inputs e fatores de ambiente são necessários.

Você não propõe nem implementa correções nesta fase. O objetivo é entendimento: o que exatamente está falhando, onde e sob quais condições.

#### Fase 2 – Análise de padrões
Quando a reprodução for confiável:

- Varie um fator de cada vez (inputs, configuração, ambiente) para ver o que muda no resultado.
- Procure fronteiras: valores ou condições em que o comportamento muda de sucesso para falha.
- Use logs, asserts ou instrumentação temporária para afunilar o caminho que está falhando.

Ao final da Fase 2, você deve entender o contorno do problema e as condições que o disparam, não apenas a mensagem de erro final.

#### Fase 3 – Hipótese e desenho da correção
Agora você pode formular uma hipótese:

- Declare claramente qual você acredita ser a causa raiz (fluxo de dados, validação ausente, problema de timing, path incorreto, etc.).
- Desenhe uma mudança **única e focada** que enderece essa causa raiz.
- Planeje como você vai validar a hipótese usando seus passos de reprodução.

Se a hipótese falhar, você volta para investigação/análise em vez de empilhar mais correções especulativas.

#### Fase 4 – Implementação e validação
Só depois de ter uma hipótese clara você modifica código ou configuração:

- Aplique a menor mudança que ataque diretamente a causa raiz.
- Rode a reprodução mínima e depois a suíte de testes mais ampla.
- Use as orientações de:
  - `defense-in-depth.md` para adicionar validação em múltiplas camadas
  - `root-cause-tracing.md` para ter certeza de que você está corrigindo a fonte real
- Confirme que a correção é robusta (por exemplo, funciona sob carga, no CI e para casos de borda identificados na Fase 2).

Se a correção não se comportar como esperado, você **não** sai acumulando mais mudanças; você volta às fases anteriores.

### Usando as utilidades de depuração no seu projeto

#### Espera baseada em condição para testes flaky (JavaScript/TypeScript)
Testes flaky que dependem de `setTimeout` ou `sleep` costumam quebrar quando as máquinas estão mais lentas, mais rápidas ou sob carga. `condition-based-waiting.md` e `condition-based-waiting-example.ts` mostram um padrão melhor: esperar pela condição que realmente importa.

Migração típica:

```typescript
// ❌ Antes: chutando o timing
await new Promise(r => setTimeout(r, 50));
const result = getResult();
expect(result).toBeDefined();

// ✅ Depois: esperando pela condição
await waitFor(() => getResult() !== undefined);
const result = getResult();
expect(result).toBeDefined();

O arquivo condition-based-waiting-example.ts inclui helpers como:

export function waitForEvent(
  threadManager: ThreadManager,
  threadId: string,
  eventType: LaceEventType,
  timeoutMs = 5000
): Promise<LaceEvent> { /* ... */ }

Adapte esses padrões à sua própria infraestrutura de testes:

1. Copie ou reimplemente os utilitários nos helpers de teste do seu projeto.
2. Substitua chamadas arbitrárias de setTimeout/sleep por esperas baseadas em condição.
3. Rode novamente sua suíte de testes para confirmar a redução de flakiness.

Isso apoia diretamente o objetivo de systematic-debugging de eliminar causas raiz em vez de simplesmente aumentar timeouts ao acaso.

Encontrando testes que poluem estado com find-polluter.sh

Se seus testes deixam arquivos ou diretórios extras para trás, ou de outra forma poluem o estado, find-polluter.sh ajuda a localizar o teste exato responsável.

Uso (a partir da raiz do projeto, ajustando os argumentos conforme necessário):

./find-polluter.sh <file_or_dir_to_check> <test_pattern>

# Exemplo
./find-polluter.sh '.git' 'src/**/*.test.ts'

O script vai:

• Descobrir arquivos de teste que combinem com o padrão informado
• Executar cada um individualmente com npm test <file>
• Após cada execução, verificar se o arquivo ou diretório alvo agora existe
• Parar e reportar o primeiro teste que o criou, com comandos para você reexecutar e inspecionar esse teste

Isso se encaixa na Fase 1 e na Fase 2 de systematic-debugging, fornecendo uma forma confiável de reproduzir e isolar poluição de estado.

Aplicando validação em defense-in-depth

Quando a sua investigação revela um bug causado por dados inválidos ou suposições incorretas, defense-in-depth.md recomenda colocar validação em várias camadas:

• Validação no ponto de entrada – Rejeitar entradas obviamente inválidas nas bordas (APIs, CLI, handlers de UI).
• Validação na lógica de negócio – Garantir que os dados façam sentido para operações específicas.
• Proteções de ambiente – Evitar operações perigosas no ambiente ou path errado.
• Logging diagnóstico – Fornecer contexto útil caso algo passe pelos filtros.

Por exemplo, validando um argumento workingDirectory:

function createProject(name: string, workingDirectory: string) {
  if (!workingDirectory || workingDirectory.trim() === '') {
    throw new Error('workingDirectory cannot be empty');
  }
  if (!existsSync(workingDirectory)) {
    throw new Error(`workingDirectory does not exist: ${workingDirectory}`);
  }
  if (!statSync(workingDirectory).isDirectory()) {
    throw new Error(`workingDirectory is not a directory: ${workingDirectory}`);
  }
  // ... proceed
}

Use esses padrões ao implementar correções da Fase 4 para garantir que o bug não volte facilmente por um caminho de código diferente.

Quando não usar esta skill

Pode ser melhor pular ou adiar systematic-debugging se:

• Você está fazendo um protótipo e aceita intencionalmente código descartável e bugs
• O problema é trivial e totalmente compreendido (por exemplo, um typo conhecido encontrado durante o desenvolvimento) e não justifica o rigor completo das quatro fases
• Você só precisa das utilidades de exemplo (como esperas baseadas em condição), e não do processo mais amplo

Mesmo nesses casos, a Lei de Ferro é um bom sinal de alerta: se você perceber que está empilhando vários chutes, é hora de mudar para systematic-debugging.

FAQ

O que systematic-debugging realmente muda no meu fluxo de trabalho?

Em vez de pular diretamente da mensagem de erro para edições de código, systematic-debugging força você a passar por investigação, análise de padrões e hipótese antes da implementação. Na prática, isso significa:

• Você captura uma reprodução confiável antes de mexer no código
• Você varia condições para entender o espaço do problema
• Você implementa uma correção focada para cada hipótese validada

O resultado são menos reverts, menos regressões ocultas e um tempo de depuração mais previsível.

Como instalo a skill systematic-debugging?

Use o comando npx skills:

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

Depois da instalação, abra a skill no seu agente ou diretório de skills e, em seguida, leia SKILL.md para ver o processo completo e os arquivos markdown de suporte com padrões e exemplos.

systematic-debugging oferece suporte a depuração em JavaScript e TypeScript?

Sim. Embora o framework em si seja agnóstico em relação à linguagem, o repositório inclui utilitários concretos focados em JavaScript/TypeScript:

• condition-based-waiting-example.ts para espera baseada em condição em testes
• Padrões em defense-in-depth.md e root-cause-tracing.md ilustrados com exemplos em TypeScript
• find-polluter.sh, que pressupõe npm test por padrão e funciona bem com test runners típicos de JS/TS

Você pode adaptar esses utilitários à estrutura e às ferramentas do seu projeto.

Posso usar systematic-debugging para automação de testes flaky?

Sim. Esse é um dos usos mais fortes da skill. Combine:

• O processo em quatro fases de SKILL.md para investigar e entender a flakiness
• condition-based-waiting.md e o exemplo em TypeScript para substituir chutes de timing por esperas baseadas em condição
• find-polluter.sh para encontrar testes que poluem estado ou criam arquivos inesperados

Juntos, esses recursos ajudam você a transformar testes instáveis em verificações estáveis e determinísticas.

systematic-debugging é apenas para testes ou também para bugs em produção?

O processo se aplica a qualquer problema técnico:

• Falhas de teste e flakiness
• Bugs e incidentes em produção
• Problemas de performance
• Falhas de build e integração

Os exemplos e utilitários são mais voltados a fluxos de desenvolvimento e testes, mas as fases e princípios são explícitos em cobrir também cenários de produção.

E se eu estiver sob pressão de tempo e só precisar de uma correção rápida?

A skill foi escrita especificamente para resistir ao impulso de “só uma correção rápida”. Ela defende que:

• Correr sem investigar a causa raiz leva a retrabalho e perda de tempo
• Correções que tratam apenas sintomas costumam criar novos problemas

Na prática, gastar alguns minutos seguindo a Fase 1 e a Fase 2 geralmente economiza tempo no geral, mesmo em incidentes urgentes.

Eu preciso seguir todas as quatro fases toda vez?

A intenção de systematic-debugging é que pular fases seja exceção, não regra. Para problemas menores e completamente compreendidos (por exemplo, um pequeno refactor em que você vê o erro imediatamente), você pode comprimir os passos. Mas se:

• O problema é recorrente
• Você não entende totalmente por que ele acontece
• Correções anteriores já falharam

…então o processo completo em quatro fases é fortemente recomendado.

Como o root-cause tracing se relaciona com defense-in-depth?

root-cause-tracing.md ajuda você a seguir um bug desde o erro visível pela cadeia de chamadas até o gatilho original. defense-in-depth.md então mostra como evitar bugs semelhantes:

• Corrigindo na fonte real
• Adicionando validação em múltiplas camadas

Por exemplo, se git init falha no diretório errado, o tracing mostra qual função passou o path incorreto, e defense-in-depth adiciona validação e proteções para que paths inválidos sejam rejeitados mais cedo.

Posso usar a skill sem copiar nenhum código do repositório?

Sim. O valor central de systematic-debugging é o processo estruturado de depuração descrito em SKILL.md. Você pode:

• Seguir as fases e regras diretamente no seu próprio ambiente
• Aplicar os padrões de investigação e análise em qualquer linguagem ou stack

Os helpers em TypeScript e Bash são aceleradores opcionais, especialmente úteis para ambientes JS/TS e Unix-like.

Onde posso explorar tudo o que está incluído em systematic-debugging?

Depois da instalação, abra a visualização de arquivos ou de repositório de obra/superpowers em skills/systematic-debugging. Os arquivos principais para inspecionar são:

• SKILL.md
• condition-based-waiting.md
• condition-based-waiting-example.ts
• defense-in-depth.md
• root-cause-tracing.md
• find-polluter.sh

Eles fornecem o fluxo completo de systematic-debugging, além de ferramentas concretas para depuração e estabilização de testes.