debuglisted

# Debug The expensive failure mode is changing code until the symptom disappears. That does not remove the bug; it moves it. You are done when you can **explain the mechanism** and **turn the failure on and off on demand**. ## 1. Reproduce — a bug you cannot trigger, you cannot fix - Get the exact command, input, and environment. Run it yourself under `.claude/tools/watch.sh` so a hang is killed with a reason (exit 124), not waited on. - Record the real, complete error: the message, the stack, the exit code. Not a summary. - **Cannot reproduce?** That is the finding. Say so and collect what is missing — version, platform, data, timing, concurrency. Do not "fix" an unreproduced bug. - Flaky? Run it 20 times and report the rate (`3/20`). A rate is a fact; "sometimes" is not, and the rate is how you will know you fixed it. ## 2. Narrow ��� halve the search space, don't tour it Pick the cheapest axis available and bisect it: - **In time** — `git bisect run <cmd>` when it used to work. This is the single highest-value debugging tool and it is consistently the one skipped. - **In input** — delete half the input; still fails? delete half again. Land on the smallest failing case and keep it, it becomes the test. - **In code** — stub, short-circuit or comment out half the path. Which half keeps it? - **In environment** — clean checkout, empty cache, the other machine, the CI container. State what you eliminated at each step. Narrowing without recording the elimination