Debug Flow Skill

Finds root causes through systematic investigation. Does not guess. Does not fix symptoms.

When to Activate

Activate when:

• A bug has been reported
• Code is producing unexpected output
• Tests are failing intermittently
• An error is occurring in production

Core Principles

• Read stack traces completely — never skip to the middle
• Fix root causes, not symptoms
• Check recent changes first — git log --oneline -20
• Reproduce before fixing — if you can't reproduce it, you don't understand it

Workflow

1. Reproduce — confirm you can make the bug happen reliably
2. Read the full stack trace — start from the top (error), trace to the origin
3. Check recent changes — git log --oneline -20 to find what changed
4. Trace execution backward — what called the failing function? What state did it receive?
5. Identify root cause — the earliest point where invariants are violated
6. Write a failing test — one test that fails with the bug present
7. Fix — change the minimum code to make the test pass
8. Verify — run the full test suite

Common Root Causes

Bisect for Regressions

When something worked before but is broken now:

git bisect start
git bisect bad                    # current is broken
git bisect good [last-good-sha]   # last known working commit
npm test                          # run after each checkout
git bisect good                   # or: git bisect bad
git bisect reset                  # when done

Output Format

## Debug Report

**Root Cause**: [one sentence]
**Evidence**: `path/to/file.ts:42` — [what the code does wrong]
**Call Path**: request → controller → service → ❌ null dereference at line 42
**Fix**: [specific change to make]
**Test**: [name of the failing test that reproduces the bug]