Systematic debugging skill: what it does and how to install it

Source: obra/superpowers · Maintainer: community: Jesse Vincent (Prime Radiant) · License: MIT · Checked: 23 October 2026

What is the systematic debugging skill?

The systematic debugging skill stops a coding agent from guessing at fixes: it has to find the root cause of a bug before it changes any code. It is for developers who are tired of agents that patch the symptom, break something else, and then pile a second patch on top.

It ships in Superpowers, the open source skill library by Jesse Vincent and Prime Radiant. The skill's description reads: "Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes". That wording matters, because the agent decides whether to load a skill from its description. This one fires before the agent proposes a fix, not after the first fix fails.

As of 23 October 2026, its skills.sh page listed about 305,000 installs, and all three security audits shown there (Gen Agent Trust Hub, Socket and Snyk) were Pass.

What does it do?

The SKILL.md is built around one rule it calls the Iron Law: "NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST". It applies to test failures, production bugs, unexpected behavior, performance problems, build failures and integration issues. It says to use it especially under time pressure, when a quick fix looks obvious, or when earlier fixes didn't work.

The agent works through four phases and must finish each one before the next:

1. Root cause investigation. Read the full error and stack trace, reproduce the bug reliably, check recent changes (git diff, new dependencies, config), and trace bad data back to where it starts. In systems with several layers, such as CI to build to signing, it adds logging at each boundary and runs once to see which layer breaks.
2. Pattern analysis. Find similar code in the same codebase that works, read any reference implementation completely, and list every difference between working and broken.
3. Hypothesis and testing. State one hypothesis ("I think X is the root cause because Y"), make the smallest change that tests it, and change one variable at a time. If it fails, form a new hypothesis instead of stacking fixes.
4. Implementation. Write a failing test that reproduces the bug, make a single fix for the root cause with no "while I'm here" changes, and verify that the test passes and nothing else broke.

Two rules stand out. If a fix fails, the agent counts its attempts; after three, it must stop and question the architecture with you rather than try a fourth. And there's a list of red-flag thoughts, such as "Quick fix for now, investigate later" or "Just try changing X and see if it works", that all mean: go back to Phase 1.

What's in the folder:

• SKILL.md: the four phases, red flags, a rationalizations table and a quick reference.
• root-cause-tracing.md: tracing a bug backward through the call stack to the original trigger.
• defense-in-depth.md: after the fix, adding validation at each layer the data passes through, so the bug can't come back by another path.
• condition-based-waiting.md and condition-based-waiting-example.ts: replacing fixed sleep or setTimeout calls in flaky tests with waits on the real condition.
• find-polluter.sh: a bash script that runs test files one by one to find which test leaves an unwanted file or state behind.
• CREATION-LOG.md and four test-*.md files: how the skill was written and the pressure scenarios used to test it.

How do you install the systematic debugging skill?

As part of Superpowers in Claude Code. The Superpowers README installs it from Anthropic's official marketplace:

/plugin install superpowers@claude-plugins-official

Plugin skills are namespaced as /plugin-name:skill-name per the Claude Code skills docs, so it shows up as /superpowers:systematic-debugging. The README also documents a second route through obra/superpowers-marketplace, plus installs for Codex, Cursor, Gemini CLI and other agents.

Just this skill. The skills CLI can copy one folder, as shown on the skills.sh page:

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

Add -g to install for all projects and -a claude-code to target Claude Code. The folder lands in .claude/skills/systematic-debugging/ in your project, or ~/.claude/skills/systematic-debugging/ with -g. Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills.

On its own, the skill still works, but it hands off to two siblings: superpowers:test-driven-development for the failing test in Phase 4 and superpowers:verification-before-completion before claiming success. Install those too if you want the full chain, or install the whole plugin.

How do you use it?

You rarely need to call it. Because the description covers any bug or test failure, Claude can load it as soon as you report one. You can also name it.

Example prompts (suggestions, not quotes from the repo):

• The checkout test fails about one run in five on CI. Debug it systematically before changing anything.
• /superpowers:systematic-debugging Our signing step fails in GitHub Actions but works locally.
• This endpoint got 3x slower after yesterday's deploy. Find the root cause first.
• Some test is creating a stray .git folder in packages/core. Find which one.
• We've tried two fixes for this race condition and neither held. What are we missing?

For the stray-file case, the bundled script runs each test file and checks for the file after each one:

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

It calls npm test on each file, so it fits JavaScript projects as written. There are no packages, API keys or other requirements beyond your project's own test runner.

Tips and limits

From the files, not from testing:

• It slows the first minute down on purpose. Expect the agent to read errors, reproduce and gather evidence before it writes code. The skill argues this is faster overall; for a typo-level fix you can tell the agent to skip it, since Superpowers says your own instructions take precedence over its skills.
• The three-fix stop needs you. When it triggers, the agent will ask to discuss architecture. Answer it; that is the point.
• "No root cause" is allowed, rarely. If the issue really is environmental, timing-dependent or external, the skill says to document what was checked, add handling such as a retry or timeout, and add logging. It also warns that most of these cases are incomplete investigations.
• What runs. Only find-polluter.sh, and only if the agent chooses to run it. It runs your tests; read it first, like any script.
• License. Superpowers is MIT, so you can copy and edit the skill if you keep the copyright notice.

How does it compare with diagnosing-bugs?

Diagnosing bugs is Matt Pocock's take on the same problem. Its first phase is building a tight pass or fail feedback loop for one hard bug, then bisecting and testing hypotheses against it. Superpowers systematic-debugging applies to every bug and leans on discipline: root cause first, one hypothesis at a time, a test before the fix, and a hard stop after three failed attempts. If you mostly fight hard, intermittent bugs, try diagnosing-bugs. If you want a default process for everything, use this one.

Save it in your Kipt library

In Kipt, open Skills and paste the skill's GitHub folder link into the import box. Kipt reads the SKILL.md and its files, including the three technique guides and find-polluter.sh; for a repo with many skills it shows a list to pick from, so you can take test-driven-development and verification-before-completion at the same time. You can also drop the folder or a .zip. Your skills live in your own private GitHub repo and install into Claude Code or Codex with one command:

npx skills add https://github.com/<you>/<repo>.git --all -g

Kipt is not affiliated with Jesse Vincent, Prime Radiant or Superpowers.

Similar skills

• Superpowers skills: the full library this skill comes from, with the TDD and code review steps around it.
• Diagnosing bugs skill: a feedback-loop-first alternative for hard bugs.
• TDD skill: Matt Pocock's red-green loop, useful for the failing test in Phase 4.
• Webapp testing skill: reproduce front-end bugs in a real browser with Playwright.