systematic-debugging Skill Review: Superpowers' No-Guessing Debug Loop

The systematic-debugging skill is a 9,465-byte markdown file whose loudest line is not subtle: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST. The source repo, obra/superpowers, showed 278,122 GitHub stars when checked for this review, with 14 SKILL.md files and an MIT license.

What the skill actually says

This is not a debugging cookbook full of language-specific tricks. It is a refusal mechanism. It tries to stop the agent from doing the one thing coding agents do when they want to please you: guess a fix and move fast.

The four phases are investigation, pattern analysis, hypothesis testing, and implementation. Phase 1 makes the agent read the error, reproduce the issue, check recent changes, gather boundary evidence in multi-component systems, and trace bad values backward. Phase 2 asks for working examples and full reference reads. Phase 3 permits one hypothesis at a time. Phase 4 says to create a failing test, implement one fix, and verify.

The most useful part is the anti-rationalization copy. It names the shortcuts: "quick fix for now," "just try changing X," "skip the test," "one more fix attempt." That matters because the skill is meant to fire under pressure, when both the human and the model want relief more than truth.

Security and source read

I read every file in skills/systematic-debugging/ and did not execute anything from the repo. The directory is mostly markdown. It also includes condition-based-waiting-example.ts, a TypeScript example, and find-polluter.sh, a shell helper that loops over test files, runs npm test "$TEST_FILE", and checks whether a target file or directory appears. That helper is not malware, but it is executable repo code. Read it before using it in a real project, especially because it runs tests selected by a pattern and, like many shell helpers, depends on file names behaving nicely.

What it costs you in context

The context number here is arithmetic from file size, not a measured API run. A rough rule is bytes / 4 ≈ tokens. By that rule, SKILL.md alone is 9,465 / 4 ≈ 2,366 estimated tokens. If an agent also pulls in the referenced files in the same directory, the loaded set becomes 40,772 / 4 ≈ 10,193 estimated tokens.

That is a fair price when you are debugging a production outage, a flaky test, or a bug that already survived one failed fix. It is silly overhead when the task is "read this stack trace and tell me the missing import." The skill's value is not token thrift. It is behavior control.

What the community reports

The public signals are stronger than usual because Superpowers has an active issue tracker and real HN mentions. They point in two directions: people like the discipline, but the skill system has rough edges around activation, naming, and prompt-trigger interactions.

How to install it

The README lists many harnesses. These commands were read from the repo during this review:

# Claude Code, official marketplace
/plugin install superpowers@claude-plugins-official

# Claude Code, Superpowers marketplace
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

# Antigravity
agy plugin install https://github.com/obra/superpowers

# Gemini CLI
gemini extensions install https://github.com/obra/superpowers

# Devin CLI
devin plugins install obra/superpowers

# Hermes Agent
hermes plugins install obra/superpowers --enable

For Hermes, the README adds a caveat: restart active sessions after installing, and start a fresh session if a very long session compacts over the first turn and loses the bootstrap.

Where it earns its keep, and where it doesn't

This skill earns its keep when the cost of a wrong fix is higher than the cost of slowing down: flaky tests, multi-layer failures, production bugs, state leaks, auth bugs, and anything where the first obvious fix has already failed. The root-cause tracing reference is the best part. It gives the model a concrete move: start where the symptom appears, ask what called it, keep walking backward, and fix the original trigger.

The criticism is real too. systematic-debugging can become performative process if invoked too broadly. The wording is intentionally rigid, and that rigidity can irritate a developer who already has the root cause and only needs a patch. Its own issue history also shows the awkwardness of instruction-heavy skills: one trigger word caused unwanted model behavior, bare skill naming caused loader confusion elsewhere in the repo, and maintainers have declined some extra evidence gates because too many gates become noise.

My take: keep it installed, but don't worship it. Use it as a seatbelt when debugging has uncertainty. Disable or ignore it when the task is already understood and the fix is mechanical.

FAQ

What does the systematic-debugging skill do?

It forces a root-cause debugging loop: investigate, compare patterns, test one hypothesis, then implement one verified fix.

How much context does it add?

SKILL.md is 9,465 bytes, about 2,366 estimated tokens using bytes / 4. The full inspected directory is 40,772 bytes, about 10,193 estimated tokens.

Is it safe?

The reviewed directory is mostly markdown, but it includes a shell script and a TypeScript example. I read them and did not execute them. You should read third-party skills before giving them agent access.

Who should use it?

Use it for bugs where guessing is risky: flaky tests, production incidents, multi-service failures, and issues that survived a first fix. Skip it for mechanical changes.

Skill by Jesse Vincent / Prime Radiant and contributors, MIT licensed. Source: github.com/obra/superpowers. Review date: August 27, 2026. Community reception shifts over time; quoted lines are short excerpts for review purposes. Context figures are file-size estimates, not measured traffic or API costs.