systematic-debugginglisted

# Systematic debugging **Trigger.** Something is broken and you do not yet know why: a crash, a wrong result, a hang, a flake, a test that fails only in CI, a regression after an upgrade. Also load it when you catch yourself about to change code in the hope that it helps. > **Reference material** (localization techniques per symptom class, > intermittent-failure playbook, and the instrumentation recipes): see > `reference.md` in this directory. ## The rule > **No edit before an explanation.** You must be able to say *this input > reaches this line, which does this wrong thing, which produces this > symptom* — before you touch the code. Guess-and-check feels faster and is not. Each speculative edit changes the system you are trying to understand, and a "fix" that removes a symptom without an explanation has usually moved the bug somewhere less visible. ## Four phases Do not skip forward. Each phase has an exit condition; if you cannot meet it, you are still in that phase. ### Phase 1 — Reproduce **Exit condition: one command that fails, reliably, on demand.** 1. Get the exact failure: full error, stack trace, exit code, wrong output. Not a paraphrase — the literal text. 2. Establish the environment: branch, commit, dependency versions, config, platform. Bugs that "only happen for them" are usually environment deltas. 3. Reduce the trigger to the smallest input and shortest command you can. 4. Run it three times. If it fails 3/3, continue. If it fails 1/3, you h