systematic-debugging · chriswiles — Claude Code skill: guide and install
systematic-debugging enforces a four-phase troubleshooting protocol rooted in root cause analysis. Ideal for tracking down broken test suites or runtime errors without trial-and-error edits.
no license ★ 6,091 updated 2026-01-06
npx skills add ChrisWiles/claude-code-showcase --skill systematic-debugging -a claude-codeWhat systematic-debugging does
The skill prevents touching production code before uncovering the true source of an error. Instead of patching visible symptoms, the agent inspects the entire stack trace, traces faulty inputs backward up the execution stack, and establishes reproducible steps. The workflow progresses through four clear stages: finding the root cause, comparing against working code, testing a single hypothesis, and creating a targeted fix.
A failing reproduction test must exist before changing code. This prevents guesswork. If three consecutive fixes fail, the workflow demands an immediate halt: repeated failures indicate architectural issues that require rethinking the design instead of adding more patches.
Specific walkthroughs cover test assertion failures, runtime exceptions, regressions diagnosed with git bisect, and race conditions. The guide also integrates with the testing-patterns skill.
What it helps with
- isolate the upstream origin of invalid data
- eliminate haphazard trial-and-error code edits
- write a reproducible failing test before patching
- debug intermittent race conditions and timing issues
Example prompts for the agent
- Inspect the stack trace in
auth.service.tsand locate the root cause following systematic-debugging - The suite in
order.spec.tsfailed: form a single hypothesis and write a reproduction test before fixing anything
How to install systematic-debugging
1Skills CLI (Vercel)
npx skills add ChrisWiles/claude-code-showcase --skill systematic-debugging -a claude-code2Manually: put the files in place
~/.claude/skills/systematic-debugging/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/systematic-debugging/
1Skills CLI (Vercel)
npx skills add ChrisWiles/claude-code-showcase --skill systematic-debugging -a codex2Manually: put the files in place
.agents/skills/systematic-debugging/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add ChrisWiles/claude-code-showcase --skill systematic-debugging -a cursor2Manually: put the files in place
.cursor/skills/systematic-debugging/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install ChrisWiles/claude-code-showcase .claude/skills/systematic-debugging2Manually: put the files in place
.github/skills/systematic-debugging/SKILL.md1Skills CLI (Vercel)
npx skills add ChrisWiles/claude-code-showcase --skill systematic-debugging -a gemini-cli2Platform CLI
gemini skills install https://github.com/ChrisWiles/claude-code-showcase --path .claude/skills/systematic-debuggingManually: put the files in place
.devin/skills/systematic-debugging/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about systematic-debugging
How to install systematic-debugging in Claude Code?
Run npx skills add ChrisWiles/claude-code-showcase --skill systematic-debugging -a claude-code in your terminal.
What does systematic-debugging do?
It directs Claude Code through a strict troubleshooting process. The agent uncovers the underlying trigger and tests assumptions rather than generating superficial fixes.
What happens if three fixes fail in a row?
The protocol commands an immediate stop. Three consecutive failed attempts indicate an architectural flaw that needs redesign discussion instead of further patching.
Similar skills
All skills for Testing and QA →systematic-debugging by other authors comes first.