Systematic Debugging
A root-cause debugging loop for coding agents: reproduce, isolate, hypothesize, then change one thing — instead of shotgun patches.
Get the complete skill folder, including its scripts and reference files.
·
When to use this skill
Use Systematic Debugging when a test is red, a prod error is looping, or the agent keeps editing unrelated files. It forces a repro and a single hypothesis before a patch.
When not to use it
Skip it for greenfield scaffolding (use TDD or Skill Creator). Skip it when the task is a known refactor with tests already covering the change.
How to install
Where will you use it?
Install the publisher’s plugin
This installs a bundle that can include other skills. Choose this method or the manual alternative below; you only need one installation.
Run these commands in Claude Code:
Claude Code CLI/plugin install superpowers@claude-plugins-official
- Ask Claude Code to use Systematic Debugging on a small task and confirm that it loads. Check the setup requirements in the publisher’s guide if it cannot run.
Alternative: install the folder manually
Use these steps if you choose the manual folder method. If you installed the plugin above, skip this alternative.
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/systematic-debugging/SKILL.md. For a shared project, commit the folder at .claude/skills/systematic-debugging/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
What supports this recommendation?
82/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 83/100
- Practical detail
- 92/100
- Source evidence
- 63/100
- Source signals
- 88/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
Try one small task
Best first exercise: diagnose a reproducible boundary error before proposing a patch.
See actual outputs and execution limits →What you need
- A coding agent with the project files, an executable test command, and a reproducible failure.
- The upstream Superpowers skill package installed for that agent.
Find why a function rejects a valid zero value.
Use systematic-debugging on this JavaScript behavior in a scratch project: function hasStock(value) { return Boolean(value); }. The intended contract is true for every non-negative integer, including 0, and false otherwise. Reproduce the zero case, trace the root cause, test one hypothesis, then propose the smallest fix with regression checks for 0, 7, -1, 1.5, null and the string "7". Show commands and observed results.Expected result
A specification to check against, not output from an AI run.
A trace from the failing zero example to truthiness, followed by a narrow fix and boundary checks.
- The report shows the zero case failing before the patch and passing afterward.
- Both 0 and 7 are accepted; negative, fractional, null, and string values are rejected.
- The cause is supported by an observed result and the final checks use the same contract.
Where this exercise stops
- This tiny deterministic fixture does not test intermittent, distributed, or production failures.
- If the issue cannot be reproduced, gather evidence before declaring a root cause.
Recorded example run
These files came from actual execution in a Codex session. They were produced and checked within the same session; this is scoped evidence, not independent review or a measured success rate.
Zero-value bug: observed failure, hypothesis and fix
Executed · Automated Codex exercise
Codex agent; Node.js 24.13.0, Python 3.12.3, Linux 7.0.0-1010-aws. Exact model version not exposed.
Executed the zero case against Boolean(value), traced the result to truthiness, compared one numeric-domain hypothesis against six fixtures, then changed one expression and reran the contract suite.
Download the actual outputs
- Run report
- Sources, snapshots and original evidence (ZIP)
- Executed command ledger
- Observed failing assertion
- Observed hypothesis output
- Passing contract output
- Final function
Recorded checks and observations
- Observed: Before the patch, the intended zero assertion failed with false !== true.
- Observed: The observed hypothesis output shows Boolean truthiness differs from the specified non-negative-integer contract.
- Observed: After the narrow fix, all six cases passed: 0, 7, -1, 1.5, null and string 7.
Scope, limitations and pinned sources
- The agent read the pinned upstream instructions and used their prescribed tools. Native Claude skill loading and general cross-agent compatibility were not tested.
- This is a tiny deterministic synthetic function, not an intermittent, distributed or production incident.
- The checks cover the stated contract cases; no no-skill control or broader model benchmark was run.
- The executor was Codex in this conversation; the exact model version was not exposed.
- These examples do not represent independent human users, customer outcomes or a compatibility certification.
Source and evidence
The upstream instructions informed this guide. The exercise and acceptance checks are an OpxSkills test recipe. Where a run is recorded, its actual outputs, environment and limits appear separately above. A recorded example does not establish general model compatibility or a success rate.
Source reviewed · Upstream revision 8ca22dba9a94
What this skill does
Agents patch symptoms. This skill makes them write down the failing signal, the smallest repro, and the check that would prove the fix — then edit.
Intended uses
- A flaky test the agent "fixed" three times
- A production error with a stack trace in-session
- A regression after a large diff
Implementation notes
- Do not accept a fix without a repro command.
- If the agent cannot reproduce, stop editing and gather evidence.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.