What does the systematic-debugging skill do?

Enforces a four-phase debugging discipline — investigate, hypothesize, test, then fix — and refuses to propose code changes until the root cause has been identified, preventing the symptom-patching cycle that creates new bugs.

When should I use the systematic-debugging skill?

Use when a bug is intermittent, when the obvious fix didn't hold, or when you find yourself reaching for try/catch as a debugging tool. Skip it for typos and other one-line bugs where the cause is self-evident.

Skills wiki

systematic-debugging

A Claude Code skill that enforces a four-phase, root-cause-first debugging discipline — investigate, hypothesize, test, then fix — and refuses to propose changes until the underlying cause has been identified.

Debug bugs by finding the cause, not by patching symptoms

Source Jesse Vincent

License MIT

First documented 2026-04-29

Debugging Code Quality

Trigger phrases

Phrases that activate this skill when typed to Claude Code:

debug this
why is this failing
this test is broken

What it does

systematic-debugging enforces a non-negotiable rule: no fixes get proposed until the root cause has been investigated. It splits a debugging session into four phases — characterize the failure, form a hypothesis, test the hypothesis, only then implement. Each phase has explicit gates, and the skill flags rationalization patterns (“I bet this is just a race condition”, “let me try fixing X first”) as red flags that mean you skipped a phase.

The point isn’t that random fixes never work. It’s that random fixes that do work mask the real cause, which then bites you later somewhere worse. The skill is a discipline against the most common Claude Code failure mode: confidently shipping a patch that addresses a symptom.

When to use it

Any test failure where the cause isn’t immediately obvious from the error
Performance issues where the suspect change “shouldn’t” cause the regression
Integration failures where multiple components could be at fault
Bugs that appear in production but not in tests — the gap is itself the clue
Whenever you catch yourself typing “let me just try…” without evidence

When not to reach for it:

Trivial fixes where the cause is the error message (typo, missing import, wrong type)
Pure refactoring with no behavioral change
New code where there’s no “bug” — there’s just “this hasn’t been built yet”

Install

From the obra/superpowers repo at skills/systematic-debugging/. The skill is part of a broader development methodology — works standalone but pairs with verification-before-completion and writing-plans.

What a session looks like

Phase 1 — Characterize. What exactly is failing? Reproduce it. Capture the full error, the full stack, the full input. Don’t paraphrase the failure.
Phase 2 — Hypothesize. What could cause this? List candidates. The skill resists the urge to commit to one too early; it wants a small set of testable possibilities.
Phase 3 — Test. For each hypothesis, design a test that would distinguish it from the others. Run it. Read the result.
Phase 4 — Implement. Only now write the fix. The fix is targeted at the confirmed cause, not the most plausible cause.

The discipline that makes it work: phases 1–3 happen before any code changes. The skill explicitly catches premature fixes (“let me just add a null check”) and routes them back to the hypothesis stage.

Receipts

TODO — to be filled in from a real debugging session. Once the skill has been activated against a non-trivial bug, this section will capture: which phase the skill caught a wrong assumption, what the hypothesis-vs-cause delta was, and whether the four-phase discipline saved or wasted time.

Source and attribution

From Jesse Vincent’s superpowers repository, part of his agent development methodology. Vincent is the author behind Prime Radiant.

License: MIT.

Quote from the skill body, verbatim: “NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.” The whole skill is built around enforcing that one rule.