Superpowers systematic debugging skill for Codex.
The systematic debugging skill from Superpowers stops Codex from guessing at fixes. It has to investigate, find the root cause and write a failing test before it changes code. It ships in the Superpowers plugin by Jesse Vincent.
Updated November 12, 2026 · 3 min read
At a glance
| Skill name | systematic-debugging |
| Comes with | The Superpowers plugin, by Jesse Vincent |
| Install | codex plugin add superpowers@openai-curated, or /plugins in Codex |
| Codex uses it | Whenever it hits a bug, a failing test or unexpected behavior, before it proposes a fix |
| Source | openai/plugins on GitHub |
What it does
The skill’s core rule is “no fixes without root cause investigation first”. Codex works through four phases and finishes each before the next:
- Root cause: read the error and stack trace in full, reproduce the bug, check recent changes, and in multi-part systems log what enters and leaves each layer to see where it breaks.
- Pattern: find similar code that works, read the reference fully, and list every difference.
- Hypothesis: state one cause and why, test it with the smallest possible change, and form a new hypothesis if it fails instead of stacking fixes.
- Implementation: write a failing test, make one fix at the source, and verify nothing else broke.
If three fixes in a row fail, the skill tells Codex to stop and question the architecture with you before trying a fourth. It also lists the thoughts that signal a shortcut, like “just try changing X and see”.
The folder includes supporting guides on tracing a bug back through the call stack, adding validation at several layers, and replacing fixed timeouts with condition polling, plus a find-polluter.sh script that bisects which test leaves unwanted files behind.
When to use it
Install it if Codex tends to patch symptoms, pile on fixes or go in circles on a bug. It is most useful on flaky tests, build failures and bugs that cross several components.
Try it
Use the systematic debugging skill. The checkout test started failing on CI after yesterday’s merge, but passes locally. Find the root cause before you change anything.
Does it work in Claude Code?
Yes. The Superpowers README lists Claude Code as a supported agent, installed from the official Claude plugin marketplace. Use that plugin rather than copying this folder, because the skill points to other Superpowers skills for test-driven development and verification.