Skip to content
Codex DesignBETA

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 namesystematic-debugging
Comes withThe Superpowers plugin, by Jesse Vincent
Installcodex plugin add superpowers@openai-curated, or /plugins in Codex
Codex uses itWhenever it hits a bug, a failing test or unexpected behavior, before it proposes a fix
Sourceopenai/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

Debug a failing test properly
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.

Keep reading

An independent plugin for Codex. Not affiliated with or endorsed by OpenAI.