debugginglisted

# Systematic Debugging When a bug is reported, a regression appears, a test fails unexpectedly, or a fix attempt doesn't work, follow this protocol. Do NOT improvise. Do NOT try random changes. This applies to user-reported runtime bugs exactly as it does to test failures during implementation — for a runtime bug, "the failing test" in Phase 1 means reproducing the reported behavior and stating the reproduction. ## Attempt Counter Track your fix attempts. Each time you modify code to fix the issue, increment the counter. - **Attempt 1-3:** Follow the 4-phase protocol below - **Attempt 3+ (ESCALATION):** STOP. See Escalation Protocol. ## Phase 1: Reproduce and Read 1. Run the failing test in isolation. Capture the EXACT error message. 2. Read the error message completely — every line, every stack frame. 3. Identify: What was expected? What actually happened? Where did execution diverge? 4. Do NOT attempt a fix yet. **Output:** A 1-2 sentence root cause hypothesis based on reading the error. ## Phase 2: Pattern Analysis 1. Compare working code vs broken code. What changed? - `git diff` to see recent changes - Compare with a similar test that passes 2. Look for the SIMPLEST explanation first: - Typo? Wrong variable name? - Missing import? Wrong path? - Stale state? Missing setup? 3. Check if the error matches a known pattern: - "Cannot find module" — import path or missing dependency - "undefined is not a function" — wrong method name or missing mo