Skip to main content
skill CX Codex

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

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

What 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 bisect to find the regression between HEAD and 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-code

2Manually: put the files in place

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

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

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

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set117

The whole set →
agent-teams Teaches Claude how to compose agent teams: which tasks split well, how many teammates to spawn, and what goes into each spawn prompt. Active only once teams are enabled. CX Codex +1 153installs generic-fullstack-ux-designer generic-fullstack-ux-designer is a Claude Code skill that guides UX design for Next.js and NestJS apps, covering loading states, optimistic UI, forms, and SSR quirks. CX Codex +1 153installs fundraising-analyzer The fundraising-analyzer skill breaks down nonprofit fundraising with donor segments, campaign ROI, retention metrics, and trend views. Use it to review results or plan campaigns. CX Codex +1 153installs microservices-architecture The microservices-architecture Claude Code skill guides microservice design, monolith decomposition, and service communication choices. It activates for distributed-system design tasks. CX Codex +1 153installs mobile-cicd mobile-cicd guides CI/CD pipelines for iOS and Android apps using Fastlane, GitHub Actions, EAS Build, and code signing configs. CX Codex +1 152installs ai-policy-generator The ai-policy-generator skill helps draft organizational AI policies, classify use-case risk, and define rules for data, oversight, ethics, and compliance. CX Codex +1 152installs generic-static-ux-designer generic-static-ux-designer is a Claude Code skill for designing static HTML, CSS, and JS interfaces with fast loads, accessibility, minimalist layouts, and no-JS fallbacks. CX Codex +1 151installs pwa-development The pwa-development Claude Code skill guides work on installable web apps with offline support. It activates for PWA builds, service worker setup, and offline-first features. CX Codex +1 150installs

Project sponsors

Companies that keep this analytics open