debugging-and-error-recovery

1# Debugging and Error Recovery
2 
3## Overview
4 
5Systematic debugging with structured triage. When something breaks, stop adding features, preserve evidence, and follow a structured process to find and fix the root cause. Guessing wastes time. The triage checklist works for test failures, build errors, runtime bugs, and production incidents.
6 
7## When to Use
8 
9- Tests fail after a code change
10- The build breaks
11- Runtime behavior doesn't match expectations
12- A bug report arrives
13- An error appears in logs or console
14- Something worked before and stopped working
15 
16## The Stop-the-Line Rule
17 
18When anything unexpected happens:
19 
20```
211. STOP adding features or making changes
222. PRESERVE evidence (error output, logs, repro steps)
233. DIAGNOSE using the triage checklist
244. FIX the root cause
255. GUARD against recurrence
266. RESUME only after verification passes
27```
28 
29**Don't push past a failing test or broken build to work on the next feature.** Errors compound. A bug in Step 3 that goes unfixed makes Steps 4-6 wrong.
30 
31## The Triage Checklist
32 
33Work through these steps in order. Do not skip steps.
34 
35### Step 1: Reproduce
36 
37Make the failure happen reliably. If you can't reproduce it, you can't fix it with confidence.
38 
39```
40Can you reproduce the failure?
41├── YES → Proceed to Step 2
42└── NO
43    ├── Gather more context (logs, environment details)
44    ├── Try reproducing in a minimal environment
45    └── If truly non-reproducible, document conditions and monitor
46```
47 
48**When a bug is non-reproducible:**
49…