Debug Loop

Prove the root cause before fixing. Every debug session follows the same loop until the problem is solved or you run out of hypotheses to test.

The Loop

1. CONTEXT    → Read error messages, logs, recent changes
2. REPRODUCE  → Run the exact command/action that fails
3. ISOLATE    → Find the single highest-leverage blocker
4. FIX        → Apply the minimal fix (one change at a time)
5. RERUN      → Run the exact same command/action again
6. PROVE      → Show runtime evidence of success

Repeat steps 3-6 until all blockers are resolved. Never skip REPRODUCE or PROVE.

Phase 1: Context

Before touching code, gather information:

1. Read the error — the full stack trace, not just the first line
2. Check recent changes — git diff HEAD~3 or recent file modifications
3. Read the config — package.json scripts, tsconfig, env files
4. Check dependencies — node_modules exists? Lock file matches?

The error message usually tells you where to look. Read it carefully.

Phase 2: Reproduce

Run the exact command the user ran (or the exact action that triggers the bug).

# Whatever they told you, run it verbatim first
pnpm dev
pnpm test
pnpm build

If it doesn't reproduce:

• Check environment differences (Node version, OS, env vars)
• Ask for exact reproduction steps
• Try rm -rf node_modules && pnpm install for dependency issues

You cannot fix what you cannot reproduce.

Phase 3: Isolate

You likely see multiple errors. Don't fix them all at once. Find the first domino:

Priority ladder

1. Missing dependency / import error — nothing works until this is fixed
2. Type error at build time — prevents compilation
3. Runtime crash on startup — app never reaches functional state
4. Runtime error on action — specific feature is broken
5. Wrong behavior — works but produces incorrect results
6. Performance issue — works correctly but too slow

Fix from the top. Lower-priority issues often disappear when higher ones are resolved.

Isolation technique

When the root cause isn't obvious:

• Binary search — comment out half the code, does it still fail?
• Minimal reproduction — extract the failing code into a standalone file
• Dependency elimination — does it fail with mocked dependencies?
• Git bisect — which commit introduced the regression?

Phase 4: Fix

Apply the minimal fix that addresses the root cause:

• Fix the cause, not the symptom
• Change one thing at a time
• Prefer upstream fixes over downstream workarounds
• If the fix is >10 lines, pause and reconsider — you might be fixing the wrong thing

Common fix patterns

Phase 5: Rerun

Run the exact same command from Phase 2. Not a different one. Not a subset.

If the original error is gone but a new one appears → go back to Phase 3 (isolate the new blocker).

If the error persists → your fix was wrong. Revert it. Go back to Phase 3 with new information.

Phase 6: Prove

Show runtime evidence that the fix works:

• Terminal output showing clean startup
• Test output showing green passes
• Browser/app screenshot showing the feature working
• HTTP response showing correct data

"I think it should work now" is not proof. Run it and show the output.

Launch Verification (for first-time startup)

When launching an app for the first time, the debug loop becomes a verification loop:

1. Install dependencies (pnpm install)
2. Check for missing env vars (.env.example vs .env)
3. Run build (pnpm build) — fix any type/compile errors
4. Run dev server (pnpm dev) — verify it starts
5. Hit the main endpoint/UI — verify it responds
6. Run tests (pnpm test) — verify test suite passes

Each step that fails enters the debug loop until resolved.

Separate Launcher from Runtime Bugs

Launcher bugs prevent the app from starting at all. Fix these first:

• Missing env vars, wrong Node version, missing deps, port conflicts, bad config

Runtime bugs appear after startup. Fix these second:

• Broken features, wrong data, UI issues, API errors

Never debug runtime issues if the app won't even start.

Handoff Summary

When debugging is complete, report:

## Debug Summary
- **Problem**: [1-sentence description of the original issue]
- **Root cause**: [what actually caused it]
- **Fix**: [what you changed, with file paths]
- **Evidence**: [command + output proving it works]
- **Regression risk**: [low/medium/high + what to watch for]

Anti-Patterns

• Fixing without reproducing — you're guessing, not debugging
• Fixing multiple things at once — you won't know which fix worked
• Downstream workarounds instead of upstream fixes — masks the real problem
• Reading code instead of running code — theories need runtime evidence
• Ignoring the stack trace — it literally tells you where the bug is
• "It works on my machine" — reproduce in the exact failing environment