# Systematic Debugging

> 4-phase root cause debugging: understand bugs before fixing them.

- Skill: `ctaxnagomi/systematic-debugging` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add ctaxnagomi/systematic-debugging`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ctaxnagomi/systematic-debugging/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: ctaxnagomi (https://skillmd.com/u/ctaxnagomi)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/ctaxnagomi/systematic-debugging

---


# Systematic Debugging

A structured 4-phase approach to debugging that forces understanding before fixing. Prevents the common trap of jumping to solutions without grasping the actual problem.

## When to Use

- A bug is reported and you need to find the root cause
- Something works locally but fails in production
- Intermittent issues that are hard to reproduce
- Any situation where "just try stuff" has failed

## Procedure

### Phase 1: Reproduce

1. Get the exact steps to reproduce the bug
2. Confirm you can reproduce it yourself
3. Note the environment, inputs, and outputs

### Phase 2: Hypothesize

1. List 3-5 possible root causes
2. For each, identify what evidence would confirm or rule it out
3. Rank by likelihood based on the symptoms

### Phase 3: Investigate

1. Test each hypothesis systematically
2. Add logging or debugging output as needed
3. Narrow down to the single root cause
4. Stop when you have evidence, not just a guess

### Phase 4: Fix and Verify

1. Write a test that reproduces the bug
2. Implement the minimal fix
3. Confirm the test passes
4. Check for regressions

## Pitfalls

- Fixing symptoms instead of root causes
- Skipping the reproduction step
- Changing multiple things at once
- Not writing a regression test

## Verification

- The original bug no longer reproduces
- The new test passes
- Existing tests still pass
- You can explain the root cause in one sentence

---

## How to use?

### 1. Download
Go to the [AGENT KD SKILL gallery](https://ctaxnagomi.github.io/agent-kd-skill/) and find this skill card. Click **Download** to save the SKILL.md file.

### 2. Install
Copy the downloaded SKILL.md into your agent's skills directory:

| Agent | Path |
|-------|------|
| **Hermes** | ~/.hermes/skills/hermes/systematic-debugging/SKILL.md |
| **opencode** | ~/.config/opencode/skills/systematic-debugging/SKILL.md |
| **Claude Code** | ~/.claude/skills/systematic-debugging/SKILL.md |

### 3. Use
Restart your agent session. The skill will auto-load when debugging is needed.

### 4. Verify
Ask your agent to debug something. If it follows the 4-phase approach, you're all set.