systematic-debugging Skill for Claude: Find the Root Cause Before Fixing

systematic-debugging makes your agent find the root cause of a bug, test failure or odd behavior before it proposes any fix.

Installs: 316.4K; on skills.sh
Stars: 310.6K; on GitHub
Files: 10; besides SKILL.md
Updated: Oct 2026; last repo commit

The skill's rule is no fixes without root cause investigation first. It works in four phases: root cause (read errors, reproduce, check recent changes, add logging at each component boundary, trace the data flow), pattern analysis, one hypothesis tested at a time, and implementation with a failing test first. It applies to test failures, production bugs, build failures and performance problems.

If three fixes fail, it stops and asks you to question the architecture. It points to the test-driven-development and verification-before-completion skills, so install the whole Superpowers set. The folder also bundles three technique guides, a TypeScript example and a shell script.

Good for

Developers whose agent guesses at fixes and piles up changes
Anyone debugging under time pressure who needs a disciplined process
Teams that want a failing test written before the fix

Install systematic-debugging

Claude Code

Copy this prompt.

Install the systematic-debugging skill in Claude Code. Run this command:

/plugin install superpowers@claude-plugins-official

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Install the plugin for the whole Superpowers set. This skill points to superpowers:test-driven-development and superpowers:verification-before-completion.

From the project README. Source.

What's in the skill

When it loads

Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes

Sections in SKILL.md

Overview
The Iron Law
When to Use
The Four Phases
Phase 1: Root Cause Investigation
Phase 2: Pattern Analysis
Phase 3: Hypothesis and Testing
Phase 4: Implementation
Red Flags - STOP and Follow Process
your human partner's Signals You're Doing It Wrong
Common Rationalizations
Quick Reference
When Process Reveals "No Root Cause"
Supporting Techniques

Key facts

Author: obra (obra/superpowers repo owner)
License: MIT
Installs on skills.sh: 316,373 as of 2026-11-02
GitHub stars: 310,635 for the whole obra/superpowers repo
skills.sh audits: Gen Agent Trust Hub pass, Socket pass, Snyk pass
What is inside: 10 files besides SKILL.md (10 in folder root)
Needs: The other Superpowers skills it names (test-driven-development, verification-before-completion)
Part of plugin: superpowers
Last commit to the repo: 2026-10-29

What it includes

Read errors, reproduce, check changes, trace data
Adds diagnostic logging at each component boundary to see where it breaks before analyzing. Points to root-cause-tracing.md for tracing backward through the call stack.
Try: “Use systematic-debugging: the signup test fails only in CI.”
Runs code · Phase 1: Root cause investigation
Compare working and broken code
Finds similar working code, reads references completely and lists every difference.
Read · Phase 2: Pattern analysis
One theory, smallest possible change
States "I think X is the root cause because Y", changes one variable and forms a new hypothesis if it fails.
Runs code · Phase 3: Hypothesis and testing
Failing test, single fix, verify
Writes a failing test first, makes one fix, and verifies with other tests. After 3 failed fixes it stops and questions the architecture with you.
Runs code · Phase 4: Implementation
root-cause-tracing, defense-in-depth, condition-based-waiting
Three guides in the folder: trace bugs backward, add checks at several layers, and replace arbitrary timeouts with condition polling.
Read · Supporting techniques

From the official docs

Permissions

Low risk

It adds logging, runs your tests and edits code while debugging. Review the diff before you keep changes.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It runs commands and edits code to debug
It adds temporary logging and runs your tests. Review the diff before you keep it.
A shell script is bundled
find-polluter.sh sits in the folder, but SKILL.md does not tell the agent to run it.

Technical details

Scopes	Reads your code and logs Adds diagnostic logging and runs tests and reproduction commands Edits code to apply a fix

Questions

What does systematic-debugging do?

It stops your agent from guessing. The agent must investigate the root cause first, then compare working code, test one hypothesis at a time, and only then write a failing test and a single fix.

How do I install it?

Use the install box at the top of this page, which has tabs for Claude Code, the Claude app and Codex. The install box uses the Superpowers plugin.

When does it trigger?

On any bug, test failure or unexpected behavior, before fixes are proposed. SKILL.md says to use it especially under time pressure or after earlier fixes failed.

What happens after three failed fixes?

The agent stops and questions the architecture instead of trying a fourth fix, and discusses it with you first.

Does it need an API key?

No key is named in SKILL.md.

Is it safe?

It is mostly instructions, but it has the agent add logging, run tests and edit code. The folder also bundles a shell script, find-polluter.sh, that SKILL.md does not mention. See the audit results under key facts.

Information

updated Nov 2, 2026

Repository: obra/superpowers
Folder: skills/systematic-debugging

obra/superpowers skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 3

obra/superpowers README · github.com
systematic-debugging SKILL.md · github.com
skills.sh listing and audits · skills.sh