Skip to content
Get packs

Systematic Debugging

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

Source Download skill
Repository
jnMetaCode/superpowers-zh
Stars
8,444
Licence
MIT
Files
11 files

What it does

When installed, this skill makes the agent follow a strict debugging method whenever something breaks, such as failing tests, build errors or unexpected behaviour. It requires the agent to reproduce the problem, gather evidence, trace where the bad value came from, compare with working code, and test one hypothesis at a time before changing code. If several fixes fail, it tells the agent to question the design rather than keep guessing.

Great for

  • Developers who keep trying quick fixes that do not stick
  • Teams debugging flaky tests or multi-component systems such as CI, builds or APIs
  • People who want an AI assistant to explain the cause before editing code

Skip it if

  • Simple tasks where a quick one-line change is clearly enough, since the process adds overhead
  • Urgent production incidents where the time-consuming process may slow down the response; the skill itself argues it is still faster, but this is a judgement call

Try asking

  • “The login tests started failing after yesterday's commit, so find out why before changing anything.”
  • “Our build fails only on CI but works locally; trace the problem through each stage.”
  • “This API call returns stale data sometimes. Investigate the root cause and propose a test that reproduces it.”
  • “Tests pass alone but fail when run together; help find which test pollutes the shared state.”
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.
  • The skill refers to other skills (test-driven-development, verification-before-completion); install those too for the full workflow.
  • Review any diagnostic commands the agent proposes before running them, especially ones that touch keychains, credentials or system state.

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 jnMetaCode/superpowers-zh 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.