# Systematic Debugging

Four-phase debugging methodology with root cause analysis.

- Repository: https://github.com/ChrisWiles/claude-code-showcase (6078 stars)
- Category: Testing
- License: see repository
- Last updated: 2026-01-06
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add ChrisWiles/claude-code-showcase --skill systematic-debugging -g -a claude-code -y`
Codex: `npx skills add ChrisWiles/claude-code-showcase --skill systematic-debugging -g -a codex -y`
Cursor: `npx skills add ChrisWiles/claude-code-showcase --skill systematic-debugging -g -a cursor -y`
Gemini CLI: `npx skills add ChrisWiles/claude-code-showcase --skill systematic-debugging -g -a gemini-cli -y`

## Description

Four-phase debugging methodology with root cause analysis. Use when investigating bugs, fixing test failures, or troubleshooting unexpected behavior. Emphasizes NO FIXES WITHOUT ROOT CAUSE FIRST.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Systematic Debugging

## Core Principle

**NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.**

Never apply symptom-focused patches that mask underlying problems. Understand WHY something fails before attempting to fix it.

## The Four-Phase Framework

### Phase 1: Root Cause Investigation

Before touching any code:

1. **Read error messages thoroughly** - Every word matters
2. **Reproduce the issue consistently** - If you can't reproduce it, you can't verify a fix
3. **Examine recent changes** - What changed before this started failing?
4. **Gather diagnostic evidence** - Logs, stack traces, state dumps
5. **Trace data flow** - Follow the call chain to find where bad values originate

**Root Cause Tracing Technique:**
```
1. Observe the symptom - Where does the error manifest?
2. Find immediate cause - Which code directly produces the error?
3. Ask "What called this?" - Map the call chain upward
4. Keep tracing up - Follow invalid data backward through the stack
5. Find original trigger - Where did the problem actually start?
```

**Key principle:** Never fix problems solely where errors appear, always trace to the original trigger.

### Phase 2: Pattern Analysis

1. **Locate working examples** - Find similar code that works correctly
2. **Compare implementations completely** - Don't just skim
3. **Identify differences** - What's different between working and broken?
4. **Understand dependencies** - What does this code depend on?

### Phase 3: Hypothesis and Testing

Apply the scientific method:

1. **Formulate ONE clear hypothesis** - "The error occurs because X"
2. **Design minimal test** - Change ONE variable at a time
3. **Predict the outcome** - What should happen if hypothesis is correct?
4. **Run the test** - Execute and observe
5. **Verify results** - Did it behave as predicted?
6. **Iterate or proceed** - Refine hypothesis if wrong, implement if right

### Phase 4: Implementation

The rest: https://github.com/ChrisWiles/claude-code-showcase/blob/HEAD/.claude/skills/systematic-debugging/SKILL.md