Systematic Debugging Skill

Systematic Debugging is a skill from Superpowers (skill source). It activates on any bug, test failure or unexpected behavior, before the agent proposes a fix, and replaces "try something and see" with a four-phase root cause process.

Its iron law: "No fixes without root cause investigation first."

Key Features

• Phase 1, root cause: read errors and stack traces completely, reproduce reliably, check recent changes, and in multi-component systems log what enters and leaves each boundary to find where it breaks.
• Phase 2, pattern analysis: find similar working code, read reference implementations fully, and list every difference.
• Phase 3, hypothesis: state one hypothesis ("X is the cause because Y"), test it with the smallest change, one variable at a time.
• Phase 4, fix: write a failing test first (via the TDD skill), apply a single fix, verify.
• Three-strikes rule: after three failed fixes, stop and question the architecture with you instead of trying a fourth.
• Supporting techniques: root-cause tracing, defense in depth, condition-based waiting (with a TypeScript example), and find-polluter.sh for tests that pollute each other.

Use Cases

• Flaky or failing tests, build failures and integration issues.
• Production bugs under time pressure, which the skill singles out as when guessing is most tempting.
• Any time the previous fix did not work.

Pricing

Free and open source under the MIT license. Prime Radiant, the company behind Superpowers, sells commercial support to enterprises. The practical cost is tokens: process skills add questions, reviews and subagent runs.

Getting Started

Superpowers installs as one plugin, so this skill arrives with the rest of the library (15 skills in v6.4.1). In Claude Code run /plugin install superpowers@claude-plugins-official. Cursor uses /add-plugin superpowers, Gemini CLI uses gemini extensions install https://github.com/obra/superpowers, and the README lists commands for Codex, GitHub Copilot CLI, OpenCode, Pi and other harnesses. Skills trigger on their own; you can also ask for one by name. Then report a bug; the agent should start by reproducing it and gathering evidence, not by editing code.

Limitation: the process is slower on truly trivial bugs, and adding diagnostic logging to each layer creates temporary noise you need to remove afterward.

FAQ

Will the agent still fix the bug?

Yes, in Phase 4, after it can explain the cause.

What stops it looping forever?

The three-failed-fixes rule hands the decision back to you.

Alternatives

• Andon: turns each agent defect into a lasting countermeasure.
• Unlazy: forces substantial work through runnable acceptance gates.
• Verification Before Completion: confirms the fix with fresh evidence.

Conclusion

It makes an agent debug like a careful engineer instead of a slot machine. More in the skills hub.