debugging

name	debugging
description	Systematic debugging — find root cause before attempting fixes, 4-phase investigation process

Systematic Debugging

Find the root cause before touching the code. Every fix without a verified root cause is a coin flip.

Quick Reference

Aspect	Detail
Trigger	Bug report, failing test, unexpected behavior, error message
Input	Error output, stack trace, user report, failing test, or observed misbehavior
Output	Root-cause statement, minimal fix, regression test, verification evidence
Gate rule	You MUST complete Phase 1 before proposing any fix
Escalation	After 3 failed fix attempts → stop, reassess architecture with human partner

Phases

Phase	Goal	Gate (exit when true)
1. Investigate	Identify root cause	Root cause stated as a falsifiable claim
2. Analyze	Confirm via pattern comparison	Difference between working and broken code documented
3. Hypothesize	Single testable prediction	Hypothesis written as "Changing [X] produces [Y] because [Z]"
4. Fix	Minimal correct change	Failing test passes, no regressions

---

Phase 1: Root Cause Investigation

1. Read the full error message and stack trace. Extract: error type, file/line location, triggering input.
2. Reproduce consistently. Write exact steps. If it doesn't reproduce, you don't understand it yet.
3. Check recent changes. git diff, new dependencies, config changes — narrow the blast radius.
4. Log at each boundary in multi-component systems. Capture: timestamps, payloads, status codes.
5. Trace data flow backward through the call stack to the original trigger.

Gate: State the root cause as a single sentence before moving on.

Example — Phase 1

BAD (skipping investigation):
  "TypeError: Cannot read property 'id' of undefined"
  → "I'll add a null check on line 42."

GOOD (investigating):
  "TypeError: Cannot read property 'id' of undefined at UserService.getProfile:42"
  → git diff shows fetchUser was changed yesterday to return { data: user } instead of user
  → Line 42 reads `user.id` but now receives the wrapper object
  → Root cause: fetchUser response shape changed; callers were not updated

Phase 2: Pattern Analysis

1. Find a working example of the same pattern in the codebase.
2. Diff working vs broken line-by-line. Document each difference.
3. List the assumptions the broken code makes about its inputs, environment, and call order.

Phase 3: Hypothesis and Testing

1. Write the hypothesis in this format: "Changing [X] will produce [Y] because [Z]."
2. Test one variable at a time — smallest possible change.
3. If the hypothesis is wrong, return to Phase 1 with the new evidence. Do not stack guesses.
4. If confidence is not high, state: "I'm uncertain because [reason]" before proceeding.

Example — Hypothesis

BAD:
  "Something is wrong with the config."

GOOD:
  "Changing `loadConfig` to parseInt(env.TIMEOUT) will fix the 'NaN' comparison
   because env vars are strings and the timeout check uses numeric comparison."

Phase 4: Implementation

1. Write a failing test that reproduces the bug.
2. Implement a single fix addressing the root cause only.
3. Verify: test passes, no other tests broken.
4. If fix fails:
   • < 3 attempts → return to Phase 1 with new information.

   • = 3 attempts → STOP. Reassess the architecture. Discuss with human partner.

---

MUST DO / MUST NOT DO

MUST DO	MUST NOT DO
Complete Phase 1 before proposing any fix	Skip to a fix from a stack trace alone
State root cause as a falsifiable claim	Propose a vague cause ("something in config")
Write a failing test before fixing	Skip the test and manually verify
Change one variable at a time	Stack multiple speculative changes
Escalate after 3 failed attempts	Say "one more fix attempt" after 2+ failures

Final Checklist

• Root cause identified and stated as a single sentence
• Working vs broken difference documented
• Hypothesis written as "Changing [X] produces [Y] because [Z]"
• Failing test written before fix applied
• Fix addresses root cause only — no speculative side-fixes
• All existing tests still pass
• After 3 failed attempts: stopped and escalated