session-debuglisted

# Session Debug Find the cause before changing anything. A change that addresses a symptom is not a fix. Open with one sentence saying what you are about to do and what it will produce. ## Rules 1. **No fix before the cause is known.** Finish the investigation before proposing a change, however obvious the change looks. Simple bugs have causes too, and rushing produces rework. 2. **One hypothesis, one change, one result.** State the hypothesis, make the smallest change that tests it, and read the result before doing anything else. Do not stack changes. 3. **Three failed fixes means the design is in question.** Stop, say so, and discuss the architecture with the user before a fourth attempt. 4. **Say what you do not know.** "I do not understand X yet" is a valid state; guessing is not. 5. **No fix before the work item exists.** A confirmed cause becomes a captured work item before Phase 4 changes anything. Capture is not permission: the item lands in `captured`, and the user's report of the bug is what authorizes fixing it — not the record. Investigation itself needs no work item; a change to the codebase does. ## Phase 1: Investigate - Read the error completely: message, stack trace, line numbers, codes. The answer is often in it. - Reproduce it. If it does not reproduce reliably, gather more data before forming a hypothesis. - Check what changed: recent commits, dependencies, configuration, environment. - In a system with several components, instrum