Claude Systematic Debugging skill review: verdict, safety and alternatives

Systematic Debugging is obra's Superpowers skill that stops a coding agent from patching symptoms. It allows no fix until the root cause is found and tested. We rate the reviewed v6.4.2 Recommended, 76/100, with safety grade B. Superpowers v7.0.0 fixed its secret-printing example on 10 October 2026.

Get the skill: systematic-debugging folder on GitHub · SKILL.md at the reviewed commit · skills.sh listing

What is the Systematic Debugging skill for Claude?

The Systematic Debugging skill for Claude is obra's Superpowers skill that bans fixes before root-cause investigation. It runs four phases: investigate, compare patterns, test one hypothesis, then fix with a failing test.

Systematic Debugging is an Agent Skill, a folder of instructions that a coding agent loads on demand. Our primer on Agent Skills explained covers the format. The skill's Iron Law reads "NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST". Its users are developers who hand bug fixing, failing tests and CI breakages to an agent.

The skill ships inside Superpowers, a plugin of disciplined coding skills from obra, the GitHub handle of Jesse Vincent. Superpowers routes "fix this bug" requests here through its using-superpowers bootstrap. Our Superpowers brainstorming verdict covers a sibling skill from the same plugin. Both skills scored 76 at the same commit.

The folder holds three references for deeper work. Root-cause-tracing walks a bug back through the call stack. Defense-in-depth adds checks at each layer after the fix. Condition-based-waiting replaces sleeps in flaky tests with polling.

Which systematic-debugging skill is this page about?

This page reviews the systematic-debugging skill in obra's Superpowers repository. GitHub and skill directories list it beside 5 copies and variants with similar names. Examples include ChrisWiles's copy, the samjhecht/wrangler fork and NousResearch's Hermes Agent variant. GitHub code search finds 4,720 matching SKILL.md copies, the original included.

Is the Systematic Debugging skill worth installing?

Yes, the Systematic Debugging skill is worth installing for agent bug fixing. It scores 76/100, Recommended, at Moderate confidence. Its rules are concrete, but no benchmark measures its effect on fix quality.

It is the Superpowers plugin's second most installed skill on skills.sh, after brainstorming.

• Strength: concrete gates, with no fix before Phase 1, one variable at a time and a failing test first.
• Strength: an escalation rule that stops the agent after three failed fixes.
• Strength: a maintainer who fixed #2008 in three days and merged the #2375 fix within a day.
• Weakness: a CI example at v6.4.2 that prints the IDENTITY secret it checks (#2375).
• Weakness: a waitFor snippet that does not compile (PR #1839, open).
• Weakness: test fixtures that ship with every install (#2277).

The verdict favours developers who hand bug fixing to an agent every week. The skill turns a vague request into a checklist the agent follows. Teams with CI secrets gain most from v7.0.0, where the example no longer prints the secret. Developers who mostly fix trivial bugs gain little and pay for the extra turns.

Tessl, a skill registry, lists no evals, and we found no independent benchmark. The missing evidence is a with-and-without run on real bug-fix tasks. That run needs to measure fix correctness, regressions, time, tokens and skipped Phase 1 steps.

Read our scoring method for the score bands, or browse all skills ranked by verdict.

What changed since our review?

Since our review, Superpowers v7.0.0 changed the Systematic Debugging skill on 10 October 2026. The CI example no longer prints the IDENTITY secret. The test fixtures and the waitFor snippet are unchanged. The verdict, score and grade on this page describe v6.4.2.

• SKILL.md: 2 lines changed between v6.4.2 and v7.0.0.
• Example: ${IDENTITY:+SET}${IDENTITY:-UNSET} and env | grep IDENTITY replaced with a SET or UNSET report and printenv IDENTITY >/dev/null.
• Issue #2375: closed on 2026-09-26 on the dev branch, released in v7.0.0 through PR #2380.
• Release note: "The multi-layer diagnostic example no longer prints the secret it checks for."
• Marketplace: the official Claude plugin marketplace pins bb92a77, which is v7.0.0.
• Open on 2026-10-21: #2277 (fixtures ship with installs) and PR #1839 (waitFor does not compile).

How many tokens does the debugging skill use?

The debugging skill file measures about 2,366 tokens per load, and its three references add about 3,122 when opened. Our estimate for one bug fix is 40,000 input and 6,000 output tokens.

The estimate assumes 5 bug fixes a week. The larger hidden cost is time. The skill adds investigation and test-writing turns to every bug, trivial ones included. It chains into the test-driven-development and verification-before-completion skills, which add their own turns.

Is the Systematic Debugging skill safe to install?

Yes, the skill is safe to install with one caution. The Systematic Debugging skill carries safety grade B: instructions plus two small example scripts, with no network calls. At v6.4.2 one CI example prints the secret it checks.

Grade B means scripts are present and nothing alarming was found. What the files at commit 8ca22db show:

• Script: find-polluter.sh is a bash bisection helper that runs npm test per file and checks whether a path appears.
• Example: condition-based-waiting-example.ts is a TypeScript polling helper, and nothing runs automatically.
• Network: the folder has no endpoints, telemetry, hooks or MCP config.
• Secret echo: the multi-layer example prints the IDENTITY value through a parameter expansion and an env grep (#2375).
• Fixtures: test-pressure-1, 2 and 3 open with imperative role-play prompts that SKILL.md never references (#2277).
• Reminder string: an earlier "Ultrathink" string that triggered a Claude Code reasoning reminder was renamed in #1558.
• Audits: skills.sh lists Gen Agent Trust Hub, Socket and Snyk as Pass.

The secret echo matters because agents copy examples verbatim. One copied line puts a credential in CI logs. Version 7.0.0 fixes that line, so install the current release. The fixtures still ship, and an agent grepping the folder can read them. Our guide to vetting skills for leaks and risks applies the same checks to any skill.

As context, Snyk's ToxicSkills research reports 13% of scanned skills with critical flaws and 36% with prompt injection (snyk.io).

What does the community report about Systematic Debugging?

The community reports that Systematic Debugging works, with refinements suggested after real use. Users in #2232 and #1955 proposed added steps after days and months of use. The maintainer fixed #2008 in three days and #2375 in one.

We counted 15 evidence items from April to September 2026, 7 of them strong. Evidence confidence is Moderate.

Most strong items report defects in examples, scripts or packaging. None reports agents ignoring the root-cause gate. Field users in #2232 and #1955 kept the method and proposed extra steps. The maintainer accepts fixes for real failures and declines rewrites without evals (#1921).

Some third-party listings, such as the mcpmarket copy, repeat a "15-30 minutes, 95% first-time fix rate" figure as fact. It traces to earlier publisher text, and we found no measurement behind it.

What are the Systematic Debugging skill's known failures?

The Systematic Debugging skill's three worst known failures at v6.4.2 sit in its examples and packaging. Its CI example prints the IDENTITY secret (#2375). The waitFor snippet does not compile (PR #1839), and test fixtures ship with installs (#2277).

Issue states are as of 2026-10-21.

1. Secret echo in the CI example (#2375): fixed on dev by PR #2380 and released in v7.0.0 on 2026-10-10.
2. Broken waitFor snippet (PR #1839, open): the snippet in condition-based-waiting.md lacks a required description argument.
3. Shipped fixtures (#2277, open): CREATION-LOG.md and four fixtures install with the skill. Fix PR #2291 was open at review.
4. Missing upstream search (PR #1884): in a vendor container, the agent kept debugging locally instead of searching upstream issues.
5. Unsized negative probes (#2232): probes not sized to the failure rate misled hypothesis tests.

Two smaller items sit in the scores. The find-polluter.sh helper splits paths on spaces (#1483). The maintainer says that bug has not triggered in practice. Tessl's review flags a stop-and-return message repeated across four sections.

Our review names the worst failure in these words:

The agent follows an example literally and leaks a secret into CI logs, or the process is skipped or misapplied so a wrong root cause is fixed with false confidence.

Does the Systematic Debugging skill work in Codex and other agents?

Yes, the Systematic Debugging skill works in Claude Code and Codex, where users filed reports from both. Cursor and OpenCode are claimed through the Superpowers plugin. No debugging run there is documented.

Claude Code is Anthropic's terminal coding agent, and it holds the most evidence for this skill. Our hub lists the best Claude Code skills we have verified. Codex is OpenAI's coding agent. Reports such as #2380 and #1884 come from users of both agents.

The skill needs bash and git. find-polluter.sh needs npm, and the rest is plain Markdown. The skill is language-agnostic, so the method applies to Python or Android code. The v7.0.0 notes add an Antigravity plugin. That claim comes from the publisher and postdates our review.

How do you install the Systematic Debugging skill?

Install the Systematic Debugging skill with the Superpowers plugin. In Claude Code, run /plugin install superpowers@claude-plugins-official. Avoid npx skills: the maintainer calls it unsupported, and it copies test fixtures into every install.

Directories show npx skills add obra/superpowers/systematic-debugging --agent claude-code (getclaudeskills). The maintainer calls that route unsupported in #2291. It pulls the pressure-test fixtures into the install, which our verdict lists as a poor fit. The official marketplace now installs v7.0.0, which carries the secret-echo fix.

How do you install it in Claude Code?

• Official route: run /plugin install superpowers@claude-plugins-official from the official Claude plugin marketplace.
• Publisher route (obra/superpowers-marketplace): run /plugin marketplace add obra/superpowers-marketplace, then /plugin install superpowers@superpowers-marketplace.

Our guide to Claude Code skill setup covers plugin scopes and skill folders.

How do you install it in Codex and other agents?

1. Open the Codex plugin marketplace.
2. Search for Superpowers.
3. Select Install Plugin.

For Cursor, the README gives /add-plugin superpowers. For Antigravity, the v7.0.0 notes give agy plugin install https://github.com/obra/superpowers. These routes are publisher-documented and unverified by us.

How do you use the Systematic Debugging skill?

Use the Systematic Debugging skill by handing the agent a failing test or bug report. The skill loads on debugging requests. It blocks any fix until the agent reproduces and traces the bug.

Steps at v6.4.2:

1. Paste the failing test, error or bug report into the session.
2. Let the agent reproduce the failure before it edits anything.
3. Read its traced root cause before you approve any change.
4. Approve one hypothesis test, with one variable changed.
5. Check the failing test it writes before the fix.
6. Stop after three failed fixes and discuss the design with the agent.

Good uses:

• Failing tests with misleading symptoms
• Flaky waits in async tests
• Multi-component CI, build and signing failures
• Bugs that resisted repeated fixes

Poor uses:

• Trivial one-line fixes
• Typos and config tweaks with an obvious cause

The multi-component case uses boundary logging. Phase 1 asks the agent to log what enters and leaves each layer. On v6.4.2, keep the CI example's echo line out of real pipelines. The find-polluter.sh helper finds which test pollutes shared state, but only with npm test.

Red flags from SKILL.md mean the agent has left the process:

• Proposing a fix before Phase 1 is complete
• Saying "one more fix attempt" after two or more failures

Test it yourself:

1. Give the agent a failing test with a misleading symptom.
2. Run it once with the skill and once without.
3. Compare whether it reproduces the failure before editing.
4. Compare whether it traces the cause before editing.

How does Systematic Debugging compare with other Claude debugging skills?

Systematic Debugging leads the Claude debugging skills we have scored, at 76/100. Hermes Agent's stricter variant and Debug Pro are unevaluated. Claude Code's /debug command reads logs and settings, not your code.

Criterion: root-cause bug fixing in a coding agent, judged by verdict score where one exists.

How our ranking differs: aiskill.market ranks by install signal and a 0 to 5 quality rubric. It puts Hermes first at 124.8K signal and Superpowers second at 173.0K. We rank by an evidence-based verdict, and only scored skills get a score. Every scored skill appears on the verdict leaderboard.

Where is the Systematic Debugging SKILL.md on GitHub?

The Systematic Debugging SKILL.md is on GitHub in obra/superpowers under skills/systematic-debugging, MIT-licensed. The folder holds 11 files, including a 9,465-byte SKILL.md and three references. We reviewed release v6.4.2, commit 8ca22db, on 30 September 2026.

• Repository: obra/superpowers, folder skills/systematic-debugging/; reviewed commit 8ca22db
• Stars: 293,541 at review, 302,529 on 2026-10-21 (GitHub)
• Forks: 26,259 at review
• Releases: 14 in 12 months; v6.4.2 on 2026-09-25, v7.0.0 on 2026-10-10
• Contributors: 37 (agenticskills.io shows 3)
• Copies: 4,720 matching SKILL.md copies in GitHub code search
• Open at review: #2277, PR #2291 and PR #1839

Install from obra or the official marketplace, since copies lag behind fixes. A copy taken from v6.4.2 still prints the secret. Directory star counts vary: getclaudeskills shows 270,274 and awesomeskill shows 20,861. The GitHub figure above is the dated one.

Common questions

Is Systematic Debugging a debugger?

No, Systematic Debugging is an instruction skill that changes how the agent investigates. It sets no breakpoints, unlike the unevaluated AlmogBaku/debug-skill debugger.

Is it the same as Claude Code's /debug command?

No, Claude Code's /debug [issue] turns on session debug logging for configuration problems (code.claude.com). For skill loading issues, read when a skill does not trigger.

Can you skip phases on a simple bug?

No, the skill says every bug goes through Phase 1. Our verdict lists trivial one-line fixes as its poor fit, because four phases are overhead there.

Does it handle multi-component systems?

Yes, Phase 1 adds boundary logging at each layer, as in its CI signing example. On v6.4.2 that example prints the IDENTITY secret, so use v7.0.0.

Is the Systematic Debugging skill free?

Yes. It ships in obra/superpowers under the MIT licence.

Does it work for Python or Android code?

Yes, the method is language-agnostic. Only find-polluter.sh is tied to a stack, since it runs npm tests.

Where does the "95% first-time fix rate" come from?

It comes from publisher text, not a measurement. SKILL.md at v6.4.2 says 95% of "no root cause" cases are incomplete investigation.