systematic-debugging · sammcj — Claude Code skill: what it does, install
systematic-debugging — a structured debugging skill for stubborn bugs that survived several fixes. It traces symptoms to root causes before proposing code changes.
Apache-2.0 ★ 173 updated 2026-10-24
npx skills add sammcj/agentic-coding --skill systematic-debugging -a claude-codeWhat systematic-debugging does
systematic-debugging organizes an investigation into four ordered phases. It first rewrites the issue in plain language, records expected and observed behavior, captures symptoms, and reviews earlier fix attempts. The next phase walks through the code as a Fagan Inspection reader, looking for logic defects, boundary failures, error-handling gaps, data-flow problems, and integration issues without changing the code yet.
The skill then uses repeated “why” questions to separate the root cause from its symptoms. It checks configuration, dependencies, runtime conditions, concurrency, timing, and assumptions that may be hiding in the design. The final phase links each proposed fix to the cause, considers side effects, and defines tests, manual checks, logging, and edge cases for verification. A sub-agent reviews the proposed solutions, while file reading, code search, tests, and logs support the investigation.
This is a poor fit for an obvious one-line bug: the workflow is meant for existing issues after several failed attempts, not for feature work or clearly environmental failures that need no code inspection.
What it helps with
- trace a stubborn bug back to its underlying cause
- inspect code line by line before changing it
- separate symptoms from defects in data flow or integrations
- test competing explanations with the Five Whys method
- turn findings into fixes and verification steps
Example prompts for the agent
- Investigate this persistent bug with systematic-debugging and complete each phase before editing the code.
- Inspect
src/api/client.tsline by line, classify every defect, and include the relevant line numbers. - Trace the failure to its root cause, then propose fixes, side effects, and tests that would verify them.
How to install systematic-debugging
1Skills CLI (Vercel)
npx skills add sammcj/agentic-coding --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 sammcj/agentic-coding --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 sammcj/agentic-coding --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 sammcj/agentic-coding Skills/systematic-debugging/SKILL.md2Manually: put the files in place
.github/skills/systematic-debugging/SKILL.md1Skills CLI (Vercel)
npx skills add sammcj/agentic-coding --skill systematic-debugging -a gemini-cli2Platform CLI
gemini skills install https://github.com/sammcj/agentic-coding --path 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 do I install systematic-debugging in Claude Code?
Run npx skills add sammcj/agentic-coding --skill systematic-debugging -a claude-code, then use ~/.claude/skills/systematic-debugging/SKILL.md.
What does systematic-debugging do?
It guides Claude Code through a staged inspection of a difficult bug, from problem framing and code review to root-cause analysis, proposed fixes, and verification.
When should I avoid using systematic-debugging?
Do not use it for simple obvious bugs, new features, or clearly environmental problems that do not require code inspection.
Source text
SKILL.md · Apache-2.0
--- name: systematic-debugging description: Applies a modified Fagan Inspection methodology to resolve persistent bugs and complex issues. Use when several fix or debugging attempts have already failed and a methodical root-cause analysis warranting a Fagan inspection is needed. Do not use for simple troubleshooting. --- # Systematic Debugging with Fagan Inspection This skill applies a modified Fagan Inspection methodology for systematic problem resolution when facing complex problems or stubborn bugs that have resisted multiple fix attempts. ## Process Overview Create tasks for each of the four phases, then work them to completion, marking each done before starting the next. Follow these four phases sequentially. Do not skip phases or attempt fixes before completing the inspection. ### Phase 1: Initial Overview Establish a clear understanding of the problem before analysis: - **Explain the problem** in plain language without technical jargon - **State expected behaviour** - what should happen - **State actual behaviour** - what is happening instead - **Document symptoms** - error messages, logs, observable failures - **Context** - when does it occur, how often, under what conditions - **Prior fix attempts** - list each attempt, what it changed, and why it failed; treat these as eliminated hypotheses that Phase 3 must account for **Output:** A clear problem statement that anyone could understand. ### Phase 2: Systematic Inspection Perform a line-by-line walkthrough as the "Reader" role in Fagan Inspection. **Identify defects without attempting to fix them yet** - this is pure inspection. Check against these defect categories: 1. **Logic Errors** 2. **Boundary Conditions** 3. **Error Handling** 4. **Data Flow Issues** 5. **Integration Points** Talk through the code step by step, as the Reader does in a Fagan inspection. For each section of code: - State what the code is intended to do - Identify any discrepancies between intent and implementation - Flag assumptions or unclear aspects - Use ultrathink to think deeper on complex sections **Output:** A categorised list of identified defects with line numbers and specific descriptions. ### Phase 3: Root Cause Analysis After identifying issues, trace back to find the fundamental cause - not just symptoms. **Five Whys Technique:** - Ask "why" repeatedly (at least 3-5 times) to get to the underlying issue - State each "why" explicitly in your analysis - Example: - Why did the API call fail? → Because the request was malformed - Why was it malformed? → Because the data wasn't serialised correctly - Why wasn't it serialised? → Because the serialiser expected a different type - Why did it expect a different type? → Because the schema was updated but code wasn't - Root cause: Schema versioning mismatch between services **Consider:** - Environmental factors (configuration, dependencies, runtime environment) - Timing and concurrency (race conditions, async issues) - Hidden assumptions in the code or system design - Historical context (recent changes, migrations, updates) **State assumptions explicitly:** - "I'm assuming X because..." - "This presumes that Y is always..." - Flag any assumptions that need verification **Output:** A clear statement of the root cause, the chain of reasoning that led to it, and any assumptions that need validation. ### Phase 4: Solution & Verification Now propose specific fixes for each identified issue. **For each proposed solution:** 1. **Describe the fix** - what code/configuration changes are needed 2. **Explain why it resolves the root cause** - connect it back to Phase 3 analysis 3. **Consider side effects** - what else might this change affect 4. **Define verification steps** - how to confirm the fix works **Verification Planning:** - Specific test cases that would have caught this bug - Manual verification steps - Monitoring or logging to add - Edge cases to validate **Use a sub-agent** as a sounding board to provide critical feedback on your proposed solutions and verification plan. **Output:** A summary of findings (key defects and root cause), a prioritised list of proposed fixes with rationale, and a verification plan for confirming the fixes work. ## Important Guidelines - **Complete each phase thoroughly** before moving to the next - **Flag unclear aspects** rather than guessing - if something is uncertain, say so - **Use available tools** - read files, search code, run tests, check logs - **Focus on systematic analysis** over quick fixes - **Validate flagged aspects** - after completing all phases, revisit any unclear points and verify them with tools ## Final Output After completing all four phases, unless the user indicates otherwise, proceed to implement the proposed solutions. ## When This Skill Should NOT Be Used - For simple, obvious bugs with clear fixes - When the first debugging attempt is still underway - For new features (this is for debugging existing code) - When the problem is clearly environmental (config, infrastructure) and doesn't require code inspection
© sammcj · Apache-2.0 · sammcj/agentic-coding
Similar skills
All skills for Code review and refactoring →systematic-debugging by other authors comes first.