Systematic Debugging (obra/superpowers)

tl;dr: the debugging path from obra/superpowers. Iron law: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST. Four phases — Root Cause → Pattern → Hypothesis → Implementation — and a hard stop after three failed fix attempts to question the architecture instead of guessing again.

What it actually does

The SKILL.md (fetched 2026-09-10) lays out four phases you must complete in order:

Phase 1 — Root Cause Investigation

1. Read errors carefully. Stack traces, line numbers, error codes. Don’t skip past warnings.
2. Reproduce consistently. If you can’t trigger it on demand, gather more data, don’t guess.
3. Check recent changes. git diff, new dependencies, config changes, environment differences.
4. Add instrumentation at component boundaries in multi-layer systems. Log what enters and exits each layer. One pass to gather evidence, then analyze which layer fails. The skill’s worked example is signing (workflow → build → signing) — env vars at one layer, not the next.
5. Trace data flow backward when the error sits deep in a call stack. See root-cause-tracing.md in the same directory.

Phase 2 — Pattern Analysis

Find a working example in the same codebase. Compare differences. Don’t assume “that can’t matter” — list every delta. Read reference implementations completely before adapting; partial understanding guarantees bugs.

Phase 3 — Hypothesis and Testing

State one hypothesis in writing: “I think X because Y.” Make the smallest possible change to test it. One variable at a time. If it doesn’t work, form a new hypothesis — don’t pile on more fixes.

Phase 4 — Implementation

1. Write a failing test first. Test-driven, not “verify after.”
2. One fix. Address the root cause, not the symptom. No “while I’m here” improvements.
3. Verify with verification-before-completion before claiming success.
4. If the fix doesn’t work: count attempts. <3 → return to Phase 1. ≥3 → STOP and question the architecture (see Phase 4.5).

Phase 4.5 — If 3+ Fixes Failed: Question Architecture. The signal is structural: each fix reveals new shared state or coupling somewhere else, fixes require “massive refactoring,” or each fix creates new symptoms elsewhere. That’s not a failed hypothesis — that’s the wrong pattern. Discuss with your human partner before attempting more fixes.

The Iron Law

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

The skill states this verbatim: “Violating the letter of this process is violating the spirit of debugging.” If you haven’t completed Phase 1, you cannot propose fixes. Every red flag below means STOP and return to Phase 1:

• “Quick fix for now, investigate later”
• “Just try changing X and see if it works”
• “Add multiple changes, run tests”
• “It’s probably X, let me fix that”
• “One more fix attempt” (when already tried 2+)
• “Each fix reveals new problem in different place”

When to use, when not

The skill is explicit: “Don’t skip when issue seems simple (simple bugs have root causes too). Don’t skip when you’re in a hurry (rushing guarantees rework). Don’t skip when manager wants it fixed NOW (systematic is faster than thrashing).”

When it fires

Frontmatter description: “Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes.” Hosts that load skill metadata (Claude Code, Cursor via plugins) pick this up automatically. The same using-superpowers bootstrap that injects brainstorming triggers this on any error/exception/failure pattern in the conversation.

Install

# Claude Code — official Anthropic marketplace
/plugin install superpowers@claude-plugins-official

# Claude Code — Superpowers marketplace (alternative)
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

The README documents ten+ other install surfaces (Antigravity, Codex App/CLI, Cursor, Devin CLI, Factory Droid, Gemini CLI, GitHub Copilot CLI, Grok Build CLI, Kimi Code, OpenCode, Pi, Hermes Agent). None of them is npx skills add obra/superpowers — that is the skills.sh command for a different ecosystem. Do not invent that name.

To load just this SKILL.md without the rest of the methodology, clone the repo and copy skills/systematic-debugging/SKILL.md into the host’s skills directory.

Gotchas

• The Iron Law has no exception. The skill lists eleven rationalizations that all collapse into “you skipped Phase 1.” The single most expensive shortcut is “I’ll write the test after confirming the fix works” — fixes without tests don’t stick.
• 3+ failed fixes is a structural signal, not “try harder.” When each fix reveals a new problem in a new place, that is the architecture, not the bug. Discuss with your human partner before fix #4.
• Environmental / timing / external “no root cause” findings are rare. The skill states explicitly: “95% of ‘no root cause’ cases are incomplete investigation.” Document what you checked, add monitoring, but don’t declare “no root cause” after two probes.
• Defense-in-depth is part of the fix, not a substitute for it. The same directory ships defense-in-depth.md (validate at multiple layers) and condition-based-waiting.md (replace arbitrary timeouts). Use them after root cause is found, not instead of finding it.
• Don’t replace arbitrary timeouts with bigger timeouts. Agents (and humans) reach for sleep(1000) → sleep(5000) → sleep(10000) instead of finding the race. The skill calls this out by name.
• Human-partner redirection phrases to watch for. “Is that not happening?” (you assumed without verifying), “Will it show us…?” (you skipped evidence-gathering), “Stop guessing,” “Ultra-think this” (question fundamentals, not symptoms), “We’re stuck?” (your approach isn’t working). All of these mean return to Phase 1.
• Cursor is partial, not full. Cursor’s skill metadata is thinner than Claude Code’s; the trigger may not fire as reliably. If your debugging session starts producing guesses, the skill is not loaded.
• sandbox_test is untested — we read the file, we did not run a real bug-to-fix drill in the sandbox. Per config/skill-safety.md, this stays untested until a human runs the eval-vs-prompt harness.

Related

• Brainstorming (obra/superpowers) — same upstream-thinking methodology; systematic debugging assumes you’ve already framed the problem
• Receiving Code Review (obra/superpowers) — when the debug trace ends at a reviewer-flagged issue, this is the protocol for responding to their finding
• Dispatching Parallel Agents (obra/superpowers) — when independent test failures are debugging, this is the parallel-investigation path
• Subagent-Driven Development (obra/superpowers) — the per-task review loop catches the kind of symptom-fix this skill exists to prevent