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, instrument the boundaries before guessing where it breaks: log what enters and leaves each component, run once, and let the evidence point at the failing one. Then investigate that component.
• When the error is deep in a call stack, trace the bad value backwards to where it originates and fix it there. references/root-cause-tracing.md describes the technique.

Phase 2: Compare

• Find working code that does something similar in the same codebase.
• If the broken code follows a reference pattern, read the reference fully before judging the deviation.
• List every difference between working and broken, however small.
• Note the dependencies and assumptions the broken path relies on.

Phase 3: Hypothesis

• Write the hypothesis down: "X is the cause because Y."
• Test it with the smallest possible change. One variable at a time.
• Confirmed: go to Phase 4. Not confirmed: form a new hypothesis, and do not leave the failed change in place.

Phase 4: Fix

• Capture the work item first. Hand /session-add-task the confirmed cause, in Mode A: the reporter's words verbatim as original_request, the root cause you established as the interpreted intent, the corrected behaviour as the scope, and the reproduction as the Test. It allocates the identity and writes the record with the runtime. Report the SEQ-NNN before you change a line, so the fix, its evidence, and its cause share one home. A bug filed as an issue carries its URL into source and annotations; one reported in conversation carries neither, and no URL is invented for it.
• Reproduce the bug in the smallest form you can: an automated test where the project has a framework, otherwise a one-off script.
• Make the one change that addresses the cause. No unrelated improvements, no bundled refactoring.
• Run the reproduction and the surrounding tests. Report what you ran and what it printed.
• Keep the regression test where the project keeps tests for this kind of change; drop the scratch script.
• Record the outcome against the captured identity: what the cause was, what the fix was, and what the test printed. The record is where the next session reads this, not the transcript.
• If the fix does not hold, count the attempts. Fewer than three: return to Phase 1 with what you learned. Three: rule 3 applies.

When there is no root cause

Sometimes a completed investigation shows the issue is environmental, timing-dependent, or external. Then document what was checked in the captured item — the investigation is the outcome even when no cause was found — add the handling that fits (a retry, a timeout, a clearer error) and the logging that would catch the next occurrence. Most "no root cause" conclusions are incomplete investigations; make sure this one is not.

Signals you have left the process

• "Quick fix now, investigate later."
• "Let me just try changing X."
• Several changes before a single test run.
• Proposing fixes before tracing the data flow.
• A second fix that reveals a new problem somewhere else.

Any of these means: return to Phase 1.

Derived from the systematic-debugging skill in superpowers by Jesse Vincent (MIT); see THIRD_PARTY_NOTICES.md. Chain context: references/workflow-overview.md.