CookiesForAI

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.

Agent skill by Jesse Vincent · Updated

Install Systematic Debugging

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

Terminal
/plugin install superpowers@claude-plugins-official

Or install only this skill with the skills CLI

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

Or paste this into your coding agent: Install the agent skill systematic-debugging from github.com/obra/superpowers. 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 October 1, 2026). 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.

  • Mutation testing: mutation-testing is Trail of Bits' agent skill for configuring mutation testing campaigns with its mewt or muton tools, reading surviving mutants, telling equivalent mutants from real test gaps, and hunting bugs they expose. (7,328 repository stars on October 2, 2026)
  • Playwright CLI: playwright-cli is Microsoft's agent skill for driving a real browser from the terminal: open pages, click and fill by element reference, take snapshots and screenshots, mock requests and generate Playwright tests. (13,721 repository stars on October 2, 2026)
  • TDD: tdd is Matt Pocock's agent skill for test-driven development: the agent agrees which public interfaces to test with you, then works one failing test and one minimal fix at a time. (273,901 repository stars on October 2, 2026)
  • Webapp Testing: Webapp Testing is Anthropic's open-source agent skill for testing local web apps: the agent writes Python Playwright scripts that click through your app, take screenshots and read console logs. (179,326 repository stars on October 2, 2026)

More from Jesse Vincent

  • Brainstorming: Brainstorming is an agent skill from Superpowers that makes your coding agent work out what you want and agree a design with you before it writes any code. (293,976 repository stars on October 2, 2026)
  • Diagnosing Superpowers: Diagnosing Superpowers is an agent skill from Superpowers that reads a session's transcripts when work went wrong and reports what happened, with every finding tied to a file and line. (293,976 repository stars on October 2, 2026)
  • Dispatching Parallel Agents: Dispatching Parallel Agents is an agent skill from Superpowers: when several problems are independent, your agent sends a focused subagent to each at once, then checks the results together. (293,976 repository stars on October 2, 2026)
  • Executing Plans: Executing Plans is an agent skill from Superpowers in which your agent works through a written plan itself, task by task with tests, then gets one fresh review of the whole branch. (293,976 repository stars on October 2, 2026)

Lists that include systematic-debugging