# Debugging

> Systematic root cause investigation before proposing fixes. Triggers: bugs, test failures, unexpected behavior, 'why is this failing', 'not working', 'broken'.

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

---


# Systematic Debugging

Fixing without understanding creates new bugs. Investigate first, fix second.

## Phase 1: Investigate

1. Read errors — stack traces, line numbers, exact messages
2. Reproduce — exact steps. Intermittent? Log at component boundaries.
3. Check recent changes — `git diff`, new deps
4. Trace data flow from symptom to source

## Phase 2: Compare

1. Find working examples in codebase
2. Read reference implementation fully
3. Diff all differences — deps, config, assumptions

## Phase 3: Hypothesize + Test

1. Form hypothesis: "X causes this because Y"
2. **Oracle test (when useful):** Compare against known-good baseline — available worktree (`git worktree list`, detached HEAD = available), reference impl, or reduced test case. Only create new worktrees for non-obvious multi-component bugs. Return to detached HEAD when done.
3. **3+ plausible hypotheses → parallelize.** Spawn one subagent per hypothesis (each traces one, reports evidence for/against). Sequential testing wastes cycles when each test is slow.
4. Smallest possible change to test. One variable at a time.
5. Confirmed → Phase 4. Refuted → new hypothesis (3rd+ → parallelize per step 3)

**Dead end:** 3 hypotheses all fail → re-enter Phase 1 with broader scope. Still stuck → escalate as architectural.

## Phase 4: Fix

1. Write failing test that reproduces the bug
2. Single fix — one change
3. Verify — test passes, no regressions
4. Fix fails? < 3 attempts → Phase 1. >= 3 → architectural issue

## 3+ Fixes = Architectural Problem

Repeated patches without root cause understanding signal a design problem. Tactical fixes compound debt and mask the real issue.

STOP. Discuss with human before more fixes.

## Red Flags → Back to Phase 1

- Proposing fixes before tracing data flow
- "It's probably X" without evidence
- Multiple changes at once (shotgun debugging)
- "Quick fix for now" / "Just try changing X"
- Skipping or deleting tests