Handoff

Freeze what this session knows and the next one cannot rebuild. The enemy is a handoff that pastes the transcript back, so the fresh session pays again for the context the clear just bought. The overcorrection is a page of headlines naming no file, command or next step, leaving the reader to rediscover the work.

Before writing

• Take no irreversible action to pause: no push, no pull request.
• Pause between atomic steps, never inside one: complete or undo the step in progress; begin no new work.
• Run branch of a plan (exo:build loop) → commit nothing; write partial work of the task in progress to a hint file such as .exo/carry/task<n>-partial.patch, and list it under ## Current state.
• Other branch than the repository's default → commit every uncommitted edit first as one chore: wip <topic> commit.
• Tree broken → say so in that commit's body.
• Default branch → leave edits uncommitted, list them under ## Current state.
• Artefact the user explicitly asked to survive the clear (question list, checklist) → preserve verbatim.

Pointers, not content

• Each section names a path, command, issue number or line range, and stops there.
• Paste no diff, file body or log; the reader can open them, and pasting spends the context the clear freed.
• Error → paste only its failing lines.
• Quote a value only when it exists nowhere on disk, such as a number from an unlogged run.

Where it goes

1. Read the location, never guess it: node "${CLAUDE_SKILL_DIR}/scripts/handoff.mjs" path prints it, the same file hooks/session-start.mjs points a resuming session at.
2. Branch name holding / → nested path: create parent directories first.
3. Write the file whole, replacing any handoff already at that path: the state it held is what this clear discards.

What it holds

First line under the H1: Written: <YYYY-MM-DD>, HEAD <short commit>, branch <name>, commit from git rev-parse --short HEAD.

Then these sections, in this order; each left out when the session has nothing true for it:

• ## Goal: what the work is for, one or two sentences, and what it will not do.
• ## Current state: what exists and works now, and what is half-built, each named by file.
• ## Decisions: one line each, <decision>, decided by <the user | this session>.
• ## Files touched: path, then one clause of what changed there.
• ## Proven: one line per claim, <claim>: <the command that proved it>, <its result>.
• ## Next step: exactly one action, the first thing the fresh session does.
• ## Then: every later step through the report to the user, numbered, each with its full command; work driving a run or loop → also how to wait for it, what to do when it fails, and where to stop and report.
• ## Open questions: what is unresolved, and who can answer it.
• ## Resume: never left out, unlike the sections above.

Last line of the file, after ## Resume: Resume: <prompt>, one sentence in the user's language telling a fresh session to read this handoff by the path handoff.mjs path printed and continue, such as Resume: lees .git/exo/handoff/<branch>.md en ga verder. The sections carry every step, so this one line suffices.

In those sections:

• User's decision → record as theirs, in their wording, never as shared.
• Plan running and <plan stem>-decisions.md beside it → carry its lines into ## Decisions unchanged.
• Claim no command proved → ## Open questions, not ## Proven.
• Read ## Current state from git status --short, not memory.
• List which changes are committed, then every uncommitted path in full, because a next session that cannot see the difference treats working-tree edits as saved and discards them.
• Session running a plan → open ## Current state with plan path and number of the task in progress.

Resume

Copy this paragraph into ## Resume exactly, so the reading session inherits the rule without this skill:

Diff what `## Proven` and `## Files touched` already cover against what `## Next step` and `## Open questions` still need, name the resume point, and repeat no step `## Proven` already covers. Verify an inherited claim against the real artifact before building on it: a prior session's report is not the proof.

References

File	Read it when
references/reconstructing-without-a-note.md	Save-session itself starts without a note and must rebuild context before saving.

Judgment

• File read this session outranks memory of it: confirm path, branch and commit with a command before writing them down.
• Short true handoff outranks a full one that guesses; what the session does not know → ## Open questions.
• Turn ends naming the written path, saying to run /clear, and quoting the Resume: prompt to paste after it. Nothing else written; no work continues after.