systematic-debugging

1# /systematic-debugging — Root Cause Before Fix
2 
3## Orientation
4 
5**Use when:** root cause is unknown and premature fixes keep failing -- enforces observe -> hypothesize -> verify before touching code.
6**Don't use when:** root cause is already known (use /marshal to implement the fix); the bug is shallow and the stack trace is enough (use /do).
7 
8## Protocol
9 
10### Phase 1: OBSERVATION & REPRODUCTION
11 
121. Read the error message, stack trace, or bug description
132. Reproduce the issue:
14   - If it's a type error: run typecheck and read the full error
15   - If it's a runtime error: identify the triggering conditions
16   - If it's a behavioral bug: document expected vs actual behavior
173. Isolate the failing component/function:
18   - What file? What function? What line?
19   - What are the inputs when it fails?
20   - Does it fail consistently or intermittently?
21 
22**Output**: A clear problem statement:
23"{Component} does {X} when it should do {Y}, triggered by {condition}"
24 
25### Phase 2: HYPOTHESIS & VERIFICATION
26 
271. Formulate up to 3 hypotheses for WHY the bug exists:
28   - H1: {most likely cause} — because {evidence}
29   - H2: {second candidate} — because {evidence}
30   - H3: {third candidate} — because {evidence}
31 
322. For each hypothesis, define a verification step:
33   - Add a console.log / diagnostic read / breakpoint
34   - Check a specific value at a specific point
35   - DO NOT change any logic yet — only observe
36 
373. Run the verification:
38   - Which hypothesis was confirmed?
39…