# Debug

> Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes. Enforces root cause investigation before fixing. No guessing, no shotgun debugging. Hard stop after 3 failed hypotheses. Use when: tests fail, errors appear, behavior doesn't match expectations, or something "just broke."

- Skill: `jessedegans/debug` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jessedegans/debug`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jessedegans/debug/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jessedegans (https://skillmd.com/u/jessedegans)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jessedegans/debug

---


# Debug

## The Rule

**No fixes without root cause investigation.** If you can't explain WHY it's broken, you can't fix it. You're just guessing.

## The Loop

### Phase 1: Investigate

- Collect symptoms: what fails, when, error messages, stack traces
- Read the relevant code (not just the error line, the surrounding context)
- Check `git log` for recent changes in affected files
- Reproduce the issue. If you can't reproduce it, you can't verify a fix.

### Phase 2: Pattern match

Does this look familiar?

| Pattern | Typical signal |
|---------|---------------|
| Race condition | Intermittent, timing-dependent, works in debug mode |
| Nil/null propagation | Crashes on missing data, works with full records |
| State corruption | Works first time, breaks on retry or concurrent use |
| Integration failure | Works locally, breaks with external service |
| Config drift | Works in one environment, not another |
| Stale cache | Works after restart, breaks after time passes |
| Off-by-one | Works for most inputs, fails at boundaries |
| Import/dependency | Works in isolation, breaks when composed |

### Phase 3: Hypothesize and test

1. Form a hypothesis: "I think X is happening because Y"
2. Design a test: add targeted logging, write a minimal reproduction, or add an assertion
3. Run it. Does the evidence support the hypothesis?

**3-strike rule:** If 3 hypotheses fail, STOP. You're probably wrong about the problem space. Step back and:
- Re-read the code from scratch
- Check your assumptions (is the data what you think it is?)
- Widen the scope (is the bug actually in the file you're looking at?)
- Ask for help

### Phase 4: Fix with minimum force

- Fix the root cause only. Smallest diff possible.
- Write a regression test that **fails without the fix**
- Don't fix adjacent issues in the same change

### Phase 5: Verify

- Reproduce the original issue. Confirm it's gone.
- Run the full test suite
- Confirm the regression test passes

## Escalation

If you've been through the loop 3+ times across multiple attempts and the bug persists, this isn't a bug. It's an architecture problem. Stop fixing symptoms and start asking: is the design wrong?

## Output Format

When reporting a fix:

```
Symptom:    [what was observed]
Root cause: [why it happened]
Fix:        [what changed]
Evidence:   [how we confirmed]
Regression: [test that prevents recurrence]
```

## Rationalization Prevention

| Thought | Reality |
|---------|---------|
| "I think I know what this is, let me just fix it" | You thought you knew last time too. Investigate first. |
| "It's probably just a typo" | Confirm it's a typo before "fixing" it. |
| "Let me try a few things" | That's shotgun debugging. Form a hypothesis first. |
| "This worked before, something must have changed" | Great. `git log` will show you what changed. Start there. |