# 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.

**Use case**: Debug bugs by finding the cause, not by patching symptoms

**Canonical URL**: https://agentcookbooks.com/skills/systematic-debugging/

**Topics**: claude-code, skills, debugging, code-quality

**Trigger phrases**: "debug this", "why is this failing", "this test is broken"

**Source**: [Jesse Vincent](https://github.com/obra/superpowers/tree/main/skills/systematic-debugging)

**License**: MIT

---

## 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](https://github.com/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

1. **Phase 1 — Characterize.** What exactly is failing? Reproduce it. Capture the full error, the full stack, the full input. Don't paraphrase the failure.
2. **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.
3. **Phase 3 — Test.** For each hypothesis, design a test that would distinguish it from the others. Run it. Read the result.
4. **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](https://github.com/obra/superpowers/tree/main/skills/systematic-debugging), 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.