How to Debug Using the Systematic-Debugging Skill in the Superpowers Plugin

The systematic-debugging skill enforces a rigorous four-phase root-cause investigation process that prevents patching symptoms and ensures every fix addresses the true source of the failure.

The systematic-debugging skill is a core component of the Superpowers development methodology available in the openai/plugins repository. Unlike ad-hoc debugging, this skill imposes a structured workflow that forces you to locate the true root cause of a failure before any code change is made. According to the source code in plugins/superpowers/skills/systematic-debugging/SKILL.md, the skill operates through four distinct phases designed to eliminate guesswork and reduce regressions.

The Four-Phase Debugging Workflow

The systematic-debugging methodology divides every debugging session into four mandatory phases. Each phase must be completed before proceeding to the next, ensuring you never patch symptoms instead of causes.

Phase 1: Root-Cause Investigation

In this initial phase, you gather comprehensive evidence about the failure. The skill requires you to read every error message, reproduce the issue reliably, check recent changes in version control, and collect evidence across component boundaries. As documented in SKILL.md, you cannot proceed to proposing fixes until you have identified the specific line or configuration that triggers the bug.

Phase 2: Pattern Analysis

Once you understand the failure, locate a working example of the same functionality elsewhere in your codebase. Compare this working implementation to the broken code and enumerate every difference, including hidden configuration files and environment variables. This comparison approach, defined in SKILL.md, reveals subtle discrepancies that often cause unexpected failures.

Phase 3: Hypothesis & Testing

Form a single, testable hypothesis that explains the root cause. Make the smallest possible change that can confirm or reject this hypothesis. If the hypothesis fails, you must iterate back to Phase 1 rather than attempting alternative fixes. This disciplined approach prevents the "shot in the dark" debugging that introduces technical debt.

Phase 4: Implementation

Create a minimal failing test using the companion test-driven-development skill, then apply the single fix that addresses your confirmed hypothesis. Verify that all tests pass, not just the new one. According to SKILL.md, if three consecutive fixes fail to resolve the issue, the skill instructs you to question the architecture rather than continuing to patch code.

Supporting Debugging Techniques

The systematic-debugging skill includes specialized utilities and guides for common debugging scenarios.

Root-Cause Tracing

The root-cause-tracing.md file provides a step-by-step "trace backwards" guide that shows how to walk up the call stack until you hit the original trigger. This technique prevents you from fixing intermediate symptoms while leaving the underlying initialization error intact.

Defense-in-Depth

After fixing the root cause, the defense-in-depth.md documentation guides you through adding validation layers that make the bug impossible to reappear. This includes input validation, preconditions, and invariant checks that fail fast if the same error condition occurs again.

Condition-Based Waiting

Replace flaky time-outs with deterministic polling loops using the patterns in condition-based-waiting.md. This eliminates race conditions in asynchronous tests by waiting for specific state changes rather than arbitrary durations.

Polluter Finder Script

When tests create unwanted files or global state (such as stray .git directories), use the find-polluter.sh Bash script. This utility bisects your test suite to isolate which specific test file creates the pollution.

How to Invoke the Skill

The systematic-debugging skill is declared as a Superpowers skill with a minimal agent interface exposed in plugins/superpowers/skills/systematic-debugging/agents/openai.yaml.

Agent Configuration

The skill exposes itself to OpenAI agents through a simple configuration:

# plugins/superpowers/skills/systematic-debugging/agents/openai.yaml

interface:
  display_name: "Systematic Debugging"
  short_description: "Find root causes before attempting fixes"

When you invoke the skill from an OpenAI-based agent, the agent automatically runs through the four phases described above. The skill does not contain executable logic; instead, it provides procedural guidelines that the agent follows to structure its investigation.

Practical Usage Examples

Prompt-Based Invocation

When working with a Superpowers-enabled agent, describe the symptom and let the agent execute the workflow:

User: My test suite is failing with "module not found: xyz". I suspect a broken import path.

Assistant (Superpowers agent): 
🛠️ Systematic Debugging – Phase 1
1. Read the full stack trace.
2. Re-run the failing test to confirm reproducibility.
3. Check recent package.json or tsconfig.json changes.

...agent proceeds through Phases 2-4 automatically...

The agent outputs investigation details, the hypothesis being tested, and the final patch once the root cause is identified.

Running the Polluter Finder

For flaky tests that create stray files:

# Find which test creates the unwanted .git directory

./plugins/superpowers/skills/systematic-debugging/find-polluter.sh '.git' 'src/**/*.test.ts'

The script runs each test in isolation and stops at the first polluter, printing the offending test file.

Adding Defensive Guards

After identifying that a function receives an empty projectDir, implement defensive validation:

// In the source file where the bug was found
function validateProjectDir(dir: string) {
  if (!dir) {
    throw new Error('projectDir must be a non-empty string');
  }
}

async function initGit(projectDir: string) {
  validateProjectDir(projectDir);
  await execFileAsync('git', ['init'], { cwd: projectDir });
}

Create a minimal failing test that expects the error, run it to confirm it fails, apply the fix, and verify all tests pass.

Summary

• The systematic-debugging skill enforces a four-phase workflow (Root-Cause Investigation, Pattern Analysis, Hypothesis & Testing, Implementation) that prevents symptom-focused patching.
• Supporting files in plugins/superpowers/skills/systematic-debugging/ provide specialized techniques for root-cause tracing, defense-in-depth, condition-based waiting, and polluter isolation.
• The skill is exposed through agents/openai.yaml as a procedural guideline for OpenAI agents rather than executable code.
• If three fixes fail, the methodology requires architectural refactoring rather than continued patching.
• The find-polluter.sh script isolates state-leaking tests through automated bisection.

Frequently Asked Questions

What makes systematic-debugging different from regular debugging?

Traditional debugging often involves trying potential fixes until the symptom disappears, which risks masking the true cause. The systematic-debugging skill forces you to prove the root cause before writing any production code, ensuring fixes are targeted and permanent.

How do I handle flaky tests that create unwanted files or state?

Use the find-polluter.sh script located in plugins/superpowers/skills/systematic-debugging/. This Bash utility bisects your test suite by running each test in isolation, stopping when it identifies the specific test that creates unwanted files or global state pollution.

What should I do if my first three hypotheses fail?

According to SKILL.md, if three attempted fixes based on different hypotheses all fail to resolve the issue, you must question the architecture rather than continuing to patch code. This rule prevents endless debugging loops and forces structural improvements when the current design is fundamentally flawed.

Can I use the systematic-debugging skill without an OpenAI agent?

Yes. While the skill exposes an interface through agents/openai.yaml for automated agents, the core methodology is documented in SKILL.md as a manual workflow. Development teams can follow the four-phase process and supporting techniques without any automation tooling.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}