Skip to content
Get packs

Systematic Debugging

Makes the agent find the root cause of a bug before proposing any fix.

Source Download skill
Repository
obra/superpowers
Stars
310,931
Licence
MIT
Files
11 files

What it does

When installed, the agent follows a structured four-phase process whenever it hits a bug, failing test, or unexpected behavior: it reads errors carefully, reproduces the problem, traces data back to its source, compares against working code, and tests one hypothesis at a time. It is designed to stop the agent from guessing and piling on quick fixes, and to make it question the overall design after several failed attempts. The folder also includes supporting guides on tracing root causes and defense-in-depth, plus a script that bisects a test suite to find which test leaves unwanted files or state behind.

Great for

  • Developers debugging flaky tests, build failures, or production bugs with an AI coding agent
  • Teams that want the agent to avoid trial-and-error patches under time pressure
  • Anyone whose agent tends to jump straight to fixes without understanding the problem

Skip it if

  • Trivial, obvious fixes where the full process adds overhead and slows things down
  • Non-technical users without a codebase to debug, since the guidance assumes code, tests, and version control
  • Running find-polluter.sh on untrusted repositories, because it executes the project's test commands (npm test) repeatedly

Try asking

  • “The login tests started failing after yesterday's merge. Debug this systematically before changing anything.”
  • “Our build fails only in CI but passes locally. Find the root cause first.”
  • “I've tried three fixes for this timeout and none worked. Help me step back and investigate.”
  • “Find which test file is creating the leftover .git directory during the test run.”
Step-by-step guide: how to use Systematic DebuggingInstall, first run, examples, tips and FAQs

Install in 3 steps

  1. 1

    Download the skill

    The ZIP contains the 11 original files, the MIT licence and an attribution note.

    systematic-debugging.zip
  2. 2

    Add it to your agent

    Claude Code (all projects)

    mkdir -p ~/.claude/skills && unzip systematic-debugging.zip -d ~/.claude/skills/

    Claude Code / Agent SDK (this project only)

    mkdir -p .claude/skills && unzip systematic-debugging.zip -d .claude/skills/

    Claude apps (web/desktop): Settings → Capabilities → Skills → Upload skill, and choose the ZIP.

  3. 3

    Ask for the task

    No special command needed — the agent reads the skill's description and loads it when your request matches. Try one of the prompts above.

Get better results

  • Give the agent the full error message and stack trace so Phase 1 has real evidence to work with.
  • Ask for the process explicitly when you want it, and review the hypothesis the agent writes down before letting it apply a fix.
  • Read find-polluter.sh and confirm the test command is safe before running it on your project.

What's inside

  • condition-based-waiting-example.ts
  • condition-based-waiting.md
  • CREATION-LOG.md
  • defense-in-depth.md
  • find-polluter.sh
  • root-cause-tracing.md
  • SKILL.md
  • test-academic.md
  • test-pressure-1.md
  • test-pressure-2.md
  • test-pressure-3.md

Redistributed unmodified from obra/superpowers under the MIT licence. The assessment was drafted with AI from the skill's files on 2026-10-29. Skills can instruct your agent to run code — read SKILL.md and any scripts before installing.