references/debugging-playbook.md

# Evidence-driven debugging

Start with a concrete symptom and a minimal reproducer; do not confuse log noise with root cause.

1. Characterize expected/actual result, affected users, environment, version, timeframe and reproducibility.
2. Gather focused stack trace, last known good behavior, relevant diff and failing test. Check whether failure is in input, state, transport, logic, storage or external dependency.
3. Generate 2–3 hypotheses and an observation that can distinguish each. Prefer a targeted diagnostic to a broad speculative rewrite.
4. Reproduce in the safest representative environment; never run destructive diagnostic commands against production by default.
5. Apply smallest complete fix, add a regression case, rerun affected tests and check adjacent failure modes.
6. State whether the exact issue was reproduced and fixed. When not reproduced, report the limited confidence.

For async failures trace retries, cancellations, concurrent state transitions, timeout boundaries and duplicate side effects.