# systematic-debugging

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.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 6091 repo stars
- Author: ChrisWiles
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/ChrisWiles/claude-code-showcase/tree/HEAD/.claude/skills/systematic-debugging/SKILL.md
- Updated: 2026-01-06
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/chriswiles-systematic-debugging

## What it 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.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add ChrisWiles/claude-code-showcase --skill systematic-debugging -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/systematic-debugging/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/systematic-debugging/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add ChrisWiles/claude-code-showcase --skill systematic-debugging -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/systematic-debugging/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add ChrisWiles/claude-code-showcase --skill systematic-debugging -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/systematic-debugging/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install ChrisWiles/claude-code-showcase .claude/skills/systematic-debugging
```

2. **Manually: put the files in place**
- File: `.github/skills/systematic-debugging/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add ChrisWiles/claude-code-showcase --skill systematic-debugging -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/ChrisWiles/claude-code-showcase --path .claude/skills/systematic-debugging
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/systematic-debugging/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/ChrisWiles/claude-code-showcase/tree/HEAD/.claude/skills/systematic-debugging/SKILL.md

## When to use it
- 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
- Inspect the stack trace in `auth.service.ts` and locate the root cause following systematic-debugging
- The suite in `order.spec.ts` failed: form a single hypothesis and write a reproduction test before fixing anything

## Similar
- [debugging-and-error-recovery](https://affpapa.org/en/nevibecode/skills/debugging-and-error-recovery.md) — skill · 79600 installs
- [debug-systematic](https://affpapa.org/en/nevibecode/skills/debug-systematic.md) — skill · 152 installs
- [service-debugging](https://affpapa.org/en/nevibecode/skills/service-debugging.md) — skill · ★ 111 repo stars
- [debugging](https://affpapa.org/en/nevibecode/skills/mrgoonie-debugging.md) — skill · 580 installs
- [debugging-toolkit-debugger](https://affpapa.org/en/nevibecode/agents/debugging-toolkit-debugger.md) — subagent · ★ 42780 repo stars
- [laravel-systematic-debugging](https://affpapa.org/en/nevibecode/skills/laravel-systematic-debugging.md) — skill · 110 installs

## Other versions with the same name
- [systematic-debugging · obra](https://affpapa.org/en/nevibecode/skills/systematic-debugging.md) — 306118 installs
- [systematic-debugging · spencerpauly](https://affpapa.org/en/nevibecode/skills/spencerpauly-systematic-debugging.md) — 604 installs
- [systematic-debugging · bobmatnyc](https://affpapa.org/en/nevibecode/skills/bobmatnyc-systematic-debugging.md) — 400 installs
- [systematic-debugging · ganyuanran](https://affpapa.org/en/nevibecode/skills/ganyuanran-systematic-debugging.md) — ★ 1450 repo stars
- [systematic-debugging · vstorm-co](https://affpapa.org/en/nevibecode/skills/vstorm-co-systematic-debugging.md) — ★ 1125 repo stars

From the same set: [chriswiles/claude-code-showcase](https://affpapa.org/en/nevibecode/by/chriswiles/claude-code-showcase.md) — 11 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
