sessions

Sessions

Context stops being available two ways: the session ends, or it gets compacted. Both lose the same thing — everything that was only ever in the conversation — and both are answered the same way, by getting that content onto disk first.

A handover is written for a reader who was not here — the next session, tomorrow's you, a teammate. What they can reconstruct from the repo stays out of it. What they cannot — why it stopped, what was decided and against what, which parts have been proven and which only look finished — is the whole content.

Every step below carries a completion criterion. Do not start the next one until the current one is checked off.

Writing a handover

Step 1 — Establish what is actually verified

Run the project's test or build command in this working tree and read the result. Then put every piece of work in flight into one of three states: verified by a run you just watched, written but never exercised, or not started.

A green suite is evidence about the code the suite covers and nothing else. Work that no test touches is unverified however green the run was, and an untested file that reads as complete is the single thing a handover most often gets wrong. Second-hand status counts the same way: work someone described as finished is verified when a run says so and not before.

• Done when the suite has been run here and every piece of work in flight carries one of the three labels.

Step 2 — Write the file

Open references/handover-template.md and write .handovers/<YYYY-MM-DD>-<slug>.md from it: five sections in this order — Where it stands, Done, Unfinished, Decisions, Next — every slot filled, the word none in a slot with nothing in it, never a deleted heading. The file is an ordinary project file: commit it when the handoff is to someone else, ignore it when it is to yourself tomorrow.

• Done when the file exists at that path, no slot holds a placeholder, and the user has been told the path and the next action.