Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add sammcj/agentic-coding --skill systematic-debugging -a claude-code
Open on GitHub

What 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.ts line 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-code

2Manually: put the files in place

~/.claude/skills/systematic-debugging/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/systematic-debugging/

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.

systematic-debugging Jesse Vincent systematic-debugging is a Claude Code and Codex skill that blocks fixes until root cause analysis is complete. It activates on test failures, bugs, or unexpected behavior. CX Codex +1 306,118installs systematic-debugging spencerpauly systematic-debugging enforces a structured debugging workflow on your AI assistant instead of random edits. It helps isolate elusive bugs and verify root causes with evidence. CX Codex +1 604installs systematic-debugging bobmatnyc The systematic-debugging skill guides an agent from reproducing a bug to checking the fix. Use it when an error or unexpected behavior has no clear cause. CX Codex +1 400installs systematic-debugging ChrisWiles 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. CX Codex +1 ★ 6,091repo stars systematic-debugging GanyuanRan The systematic-debugging skill guides bug and test-failure investigations before code changes. Use it to trace a symptom to the logic that owns the cause. CX Codex +1 ★ 1,450repo stars debugging siviter-xyz debugging is a Claude Code skill that guides root cause analysis for errors and test failures. It helps localize bugs and prepare minimal, verified fixes. CX Codex +1 151installs debug cyrusagents debug works through a reported bug from reproduction to a minimal fix. Use it when you need to trace an error and verify the result. CX Codex +1 871installs debug-systematic travisjneuman debug-systematic — a four-phase debugging skill for hard-to-reproduce failures, race conditions, and unexplained behavior. It guides the agent from reproduction to verified fix. CX Codex +1 152installs debugging-and-error-recovery addyosmani The debugging-and-error-recovery Claude Code skill traces failures to their root cause and checks the fix. It activates for failing tests, broken builds, unexpected errors, or behavior that no longer matches expectations. CX Codex +1 79,600installs debugging-toolkit-debugger Seth Hobson The debugging-toolkit-debugger subagent investigates errors, failed tests, and odd behavior by tracing failures to their cause and checking a focused fix. CX Codex ★ 42,780repo stars Debug Mode Instructions official github Debug Mode Instructions — a GitHub Copilot subagent that walks debugging in phases: reproduce the bug, find the root cause, patch it, verify. Useful when a failure is flaky and you don't know where to start. CX Codex +1 ★ 41,430repo stars

From the same set73

The whole set →
liteparse liteparse extracts text and structure from PDF, DOCX, PPTX, XLSX and images to markdown locally, no cloud or LLM required. CX Codex +1 ★ 173repo stars analyse-design The analyse-design skill examines an app, website, or document’s code and screenshots to map its design system. Use it to audit UI consistency or guide new components. CX Codex +1 ★ 173repo stars invokeai-image-gen invokeai-image-gen — a skill for generating images via local InvokeAI API, supporting FLUX.2 Klein, Z-Image Turbo, and SDXL. Auto-detects models and applies appropriate parameters, saves output as PNG. CX Codex +1 ★ 173repo stars qa-to-issues qa-to-issues runs an interactive QA session to turn reported bugs into durable GitHub issues. The agent asks quick clarifying questions, checks your codebase, and files tickets. CX Codex +1 ★ 173repo stars personal-genomics personal-genomics runs pharmacogenomics, disease-risk, carrier and trait checks on raw DNA files, entirely offline — one array export or several sources merged into a single report. CX Codex +1 ★ 173repo stars markedit-tools markedit-tools manages the MarkEdit markdown editor on macOS: installs updates, handles extensions, and edits settings via Claude Code. CX Codex +1 ★ 173repo stars raspberry-pi-pico2 Get guidance on building and debugging Raspberry Pi Pico 2 projects with the Pi Debug Probe. Useful for RP2350, SDK configuration, OpenOCD, and GDB. CX Codex +1 ★ 173repo stars prompt-enhancer prompt-enhancer transforms vague or basic prompts into the form a domain specialist would use. Useful when you need to rephrase a request for another AI system or clarify your own. CX Codex +1 ★ 173repo stars

Project sponsors

Companies that keep this analytics open