debugginglisted

# Debugging ## Purpose Turn a report into a cause. The alternative — changing things until the symptom disappears — produces code nobody understands, a bug that returns under a slightly different input, and no way to tell whether the change helped or moved the failure somewhere quieter. The discipline is cheap and it is nearly always skipped under pressure, which is exactly when guessing is most expensive. ## Workflow 1. **Restate the fault as an observation.** "Customer 88123 saw a negative balance at 14:02" is an observation. "The refund logic is broken" is a hypothesis wearing a report's clothes, and adopting it early is how the wrong subsystem gets investigated for a day. 2. **Reproduce it.** Deterministically if possible, intermittently if not — but know which, because "I cannot reproduce it" and "it reproduces one time in ten" lead to different work. If it only happens in production, collect evidence within the mitigation budget (`references/production-evidence.md`). 3. **Shrink.** Remove inputs, steps, data and configuration until removing anything more makes the fault disappear, while preserving the original failure signature. Stop when the next reduction costs more than it helps; a minimal reproduction need not identify the full cause. 4. **State a hypothesis that predicts something you have not yet looked at.** "If the cause is the missing time zone, then the row written at 23:30 local will carry yesterday's date." Also name an observ