debug-systematic — Claude Code skill: debugging and setup
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.
MIT 152 installs ★ 114 updated 2026-11-10
npx skills add travisjneuman/.claude --skill debug-systematic -a claude-codeWhat debug-systematic does
debug-systematic gives an agent a fixed path for investigating bugs. It starts by recording reproduction steps, environment details, failure frequency, and exact errors. The investigation then narrows the scope to a component, function, or line range. A repeatable failure comes first; without one, the protocol does not move into meaningful hypothesis testing.
The skill can use binary search, git bisect, code reduction, and comparisons between working and broken environments. During diagnosis, the agent forms a hypothesis, predicts what else should be observable, and checks it with logs or other evidence. The final phase keeps the change small, reviews affected callers and error paths, and checks for regression risks.
A failing test is added only when the user asks for tests. For a Git regression, the workflow can run git bisect start, git bisect bad HEAD, and git bisect good <known-good-commit>.
What it helps with
- reproduce an intermittent failure
- pin a regression to a Git change
- separate an environment issue from a code defect
- trace the cause of a race condition
- verify a fix against the original failure
Example prompts for the agent
- Investigate this bug with the four phases, starting by establishing a reliable reproduction.
- Use
git bisectto find the regression betweenHEADand the known-good commit. - Find the root cause, make the smallest fix, and review the affected error paths for side effects.
How to install debug-systematic
1Skills CLI (Vercel)
npx skills add travisjneuman/.claude --skill debug-systematic -a claude-code2Manually: put the files in place
~/.claude/skills/debug-systematic/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/debug-systematic/
1Skills CLI (Vercel)
npx skills add travisjneuman/.claude --skill debug-systematic -a codex2Manually: put the files in place
.agents/skills/debug-systematic/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add travisjneuman/.claude --skill debug-systematic -a cursor2Manually: put the files in place
.cursor/skills/debug-systematic/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install travisjneuman/.claude skills/debug-systematic2Manually: put the files in place
.github/skills/debug-systematic/SKILL.md1Skills CLI (Vercel)
npx skills add travisjneuman/.claude --skill debug-systematic -a gemini-cli2Platform CLI
gemini skills install https://github.com/travisjneuman/.claude --path skills/debug-systematicManually: put the files in place
.devin/skills/debug-systematic/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add travisjneuman/.claude --skill debug-systematic -a opencodeClaude.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 debug-systematic
How do I install debug-systematic in Claude Code?
Run npx skills add travisjneuman/.claude --skill debug-systematic -a claude-code. After installation, the skill is at ~/.claude/skills/debug-systematic/SKILL.md.
What does debug-systematic do?
It leads the agent through reproduction, isolation, diagnosis, and fix verification. The workflow uses evidence and incremental changes instead of guesswork.
Does the skill always add a regression test?
It writes a failing test only when the user has asked for tests.
Source text
SKILL.md · MIT
---
name: debug-systematic
description: Systematic 4-phase debugging methodology for complex, intermittent, or mysterious issues. Use when investigating bugs, race conditions, or unexplained failures.
---
# Systematic Debugging Protocol
A disciplined, evidence-based approach to debugging that prevents guessing and ensures root cause discovery.
## The 4-Phase Protocol
### Phase 1: REPRODUCE (Establish Ground Truth)
**Goal**: Create reliable reproduction steps before ANY investigation.
**Actions**:
1. Document exact steps to trigger the bug
2. Record environment specifics (OS, versions, config, memory, network)
3. Determine frequency: Always? Sometimes? Specific conditions?
4. Capture exact error messages, stack traces, screenshots
5. Test on different environments to isolate variables
**Key Questions**:
- When did it last work correctly?
- What changed since then? (code, deps, config, infrastructure)
- Is it environment-specific?
- Is it data-specific?
- Is it timing-specific?
**Output**: Clear reproduction steps that reliably trigger the issue.
---
### Phase 2: ISOLATE (Narrow the Scope)
**Goal**: Reduce the search space from "entire codebase" to "specific component."
**Techniques**:
**Binary Search**:
1. Identify two points: working state and broken state
2. Test the midpoint
3. Recurse into the broken half
4. Continue until the change is identified
**Git Bisect** (for regressions):
```bash
git bisect start
git bisect bad HEAD
git bisect good <known-good-commit>
# Git will checkout commits for testing
# After each test:
git bisect good # or git bisect bad
# Continue until culprit found
```
**Code Elimination**:
- Comment out sections to isolate the problem
- Create minimal reproduction case
- Strip away everything non-essential
**Environment Isolation**:
- Exercise the failing path in isolation (minimal reproduction; a unit test only when the user asked for tests)
- Compare working vs broken environments
- Use fresh installs to eliminate pollution
**Output**: "The bug is in [specific component/function/line range]"
---
### Phase 3: DIAGNOSE (Understand Root Cause)
**Goal**: Know exactly WHY the bug occurs, not just WHERE.
**Scientific Method**:
1. **Observe**: What exactly is happening?
2. **Hypothesize**: Why might this be happening?
3. **Predict**: If hypothesis is correct, what else would be true?
4. **Test**: Verify predictions with evidence
5. **Iterate**: Refine hypothesis based on results
**Logging Strategy**:
```javascript
// Add strategic logging at boundaries
console.log("[DEBUG] Function entry:", { input, state });
console.log("[DEBUG] After processing:", { result, sideEffects });
console.log("[DEBUG] Function exit:", { returnValue });
```
**Common Root Causes**:
| Symptom | Likely Causes |
| -------------------------- | -------------------------------------------------- |
| Works locally, fails in CI | Environment differences, timing, resources |
| Intermittent failure | Race condition, flaky network, resource contention |
| Works then stops working | State mutation, memory leak, cache poisoning |
| Wrong data | Type coercion, encoding, timezone, precision |
| Silent failure | Swallowed exception, async error, missing await |
**Output**: Clear explanation of the root cause with evidence.
---
### Phase 4: FIX & VERIFY (Resolve and Prevent)
**Goal**: Fix the issue and prevent regression.
**Fix Process**:
1. **Implement minimal fix** - change as little as possible
2. **Check for similar patterns** - same bug elsewhere?
3. **Review fix for side effects** - read the callers, inputs, and error paths it touches
4. **Document the fix** - why it happened, how to prevent
Write a failing test that captures the bug only when the user asked for tests.
**Verification Checklist**:
- [ ] Review shows the Phase 3 root cause is addressed, not just the symptom
- [ ] The output the fix already produces (the reproduction, the command that did the work) confirms it
- [ ] Fix works in all affected environments
- [ ] No new warnings or errors introduced
**Prevention**:
- Add guards/validation at boundaries
- Improve error messages for easier future debugging
- Document gotchas for other developers
- Consider if architectural change prevents similar bugs
---
## Debugging Anti-Patterns
**DO NOT**:
- Guess and hope (change things randomly)
- Assume you know the problem without evidence
- Trust comments/docs over actual code behavior
- Debug production with print statements you'll forget to remove
- Fix the symptom instead of the root cause
- Make multiple changes at once
**DO**:
- Verify assumptions with evidence
- Change one thing at a time
- Log actual values, not what you expect
- Trust the code over documentation
- Take breaks when stuck (fresh eyes help)
---
## Quick Reference
```
1. REPRODUCE → Can I reliably trigger this?
2. ISOLATE → Where exactly is it failing?
3. DIAGNOSE → Why is it failing?
4. FIX → How do I fix it permanently?
```
---
## Output Template
```markdown
## Bug Investigation: [Title]
### Reproduction
- Steps to reproduce
- Environment details
- Frequency
### Isolation
- Search method used
- Scope narrowed to
### Root Cause
- What's actually wrong
- Why it happens
- Evidence
### Fix
- Code changes made
- What review confirmed, and what it couldn't
### Prevention
- How to prevent similar bugs
- Documentation updates
```
© travisjneuman · MIT · travisjneuman/.claude