systematic-debugging

Systematic Debugging

Systematic Debugging is an agent skill from Superpowers that makes your agent find the root cause of a bug or failing test before it proposes any fix, instead of guessing.

Checked by CookiesForAI on : license and last change of the skill re-read from GitHub.

Written by

Install Systematic Debugging

Install only this skill with the skills CLI

Terminal
npx skills add obra/superpowers --skill systematic-debugging

Or, in Claude Code, install the whole Superpowers plugin from Anthropic's official marketplace

Agent chat
/plugin install superpowers@claude-plugins-official

Or paste this into your coding agent: Install the agent skill systematic-debugging from github.com/obra/superpowers. Checked by CookiesForAI on : license and last change of the skill re-read from GitHub. A skill can include scripts that run on your computer, so read its source first.

What Systematic Debugging does

Systematic Debugging is one of the skills in Superpowers, Jesse Vincent's open-source method for AI coding agents. It loads for any bug, test failure, build failure or unexpected behavior, before the agent proposes a fix. Its central rule: no fixes without a root cause investigation first. The rule holds when the issue looks simple, when time is short, and after earlier fixes have failed.

Under Systematic Debugging, the agent works in four phases. First it reads the error messages in full, reproduces the problem, checks recent changes, and in systems with several parts logs what enters and leaves each one to see where it breaks. Then it compares the broken code with similar working code. Then it tests one hypothesis at a time with the smallest change. Finally it writes a failing test with Test-Driven Development, makes one fix, and confirms it with Verification Before Completion.

Under Systematic Debugging, if three fixes have failed, the agent stops and questions the architecture with you instead of trying a fourth. The folder holds supporting guides on tracing a bug backward through the call stack, adding validation at several layers, and replacing fixed timeouts with waiting for a condition, plus a script that finds which test leaves unwanted files or state behind.

When to use Systematic Debugging

  • Your agent keeps trying quick fixes that do not solve the bug.
  • You have a failing test and want to know why before anything changes.
  • You have a build or CI step that breaks somewhere across several layers and cannot see where.
  • Your tests are flaky and seem to depend on timing.

When to pick something else

  • You have several unrelated failures at once: use Dispatching Parallel Agents.

Which agents Systematic Debugging works in

Jesse Vincent documents Systematic Debugging for Claude Code, Codex (app and CLI), Cursor, Gemini CLI, GitHub Copilot CLI, OpenCode, Antigravity, Devin CLI, Factory Droid, Grok Build CLI, Kimi Code, Pi, Qwen Code, Hermes Agent, Muse. The open skills CLI also installs it into 78 agents, including Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode (we listed it with the CLI on ). See where each agent looks for skills.

Superpowers is written in Claude Code's vocabulary (subagent dispatch, todos, the Skill tool) and ships tool mappings for Codex, Gemini CLI, Pi, Antigravity, Hermes Agent and Muse. Installed as the full plugin, a session-start hook loads Using Superpowers so the agent reaches for skills on its own; one skill installed with the skills CLI gets no hook and may point to sibling skills you do not have.

Systematic Debugging license

Systematic Debugging is published under MIT.

More from Jesse Vincent

Lists that include systematic-debugging