handoff

Handoff

The user is about to clear the context window. Produce a prompt that lets a fresh session, which starts with zero memory of this one, continue the work without re-deriving anything this session established.

Today's date, time and time-zone offset: !date +%FT%H:%M%z Current branch and HEAD: !git branch --show-current 2>/dev/null | grep . || echo none at !git rev-parse --short HEAD 2>/dev/null || echo none Uncommitted files: !git status --short 2>/dev/null | wc -l | tr -d ' ' Argument given by the user (may be empty): $ARGUMENTS

Procedure

1. Decide the slug. If the user gave an argument, use it (lower-case, hyphens). Otherwise derive a short slug from the next work item (the row number or feature name the next session will work on). The file is tmp/docs/<today>-handoff-<slug>.md, where <today> is the date part (YYYY-MM-DD) of the date and time printed above. Create tmp/docs/ if it does not exist. Never overwrite an existing file: if the name is taken, append -2.

2. Collect the facts, mostly from files, not from memory. Every source below is optional; use the ones the project has. Read state.md and the last two [saved] entries of session-log.md (written by the context-management skill in projects where state was saved); the previous handoff in tmp/docs/ (the newest *handoff* file) for the conventions section, or the project's CLAUDE.md when there is no previous handoff; the version file and the installed version if the project publishes a package or plugin; the project's worklist or issue file if state.md, the previous handoff or CLAUDE.md names one (the item the next session works on). Delegate bulk reads to a subagent; keep this window small.

3. Write the prompt with exactly these sections, in plain English, no idioms, every technical term defined at first use, lines at most 88 columns:

   • Header line. The file's first line is exactly Handoff: written=<YYYY-MM-DD>T<HH:MM><+hhmm> branch=<name|none> head=<short sha|none>, with the values printed above (<+hhmm> is the time-zone offset, such as +0200; <short sha> is the short commit id; none for an empty value). The /pickup skill reads it to find the newest handoff and the commits made after it. When the next task has an end state that a commit may not show, the second line is Done when: <one checkable condition>.
   • Opening paragraph. The task in one or two sentences, naming the row or feature and the file and line where it is described; the repository, the branch, the version, whether the tree is clean, and whether the installed plugin matches main.
   • ## What is already known (do not re-derive). Every fact this session verified that the next session would otherwise have to re-measure: figures, with the transcript ids or file:line they came from; decisions the user made, stated as decisions; contradictions found between documents and evidence; what was rejected and why, in one line each; the exact commands that produced key evidence when they were not obvious. Facts only, each with its source.
   • ## How to proceed. Numbered steps, in the order the next session should take them. Name the design step when one is needed (independent lenses plus a rebuttal round before tallying), the point where the user decides, and the delivery shape (spec plus orchestrated run, or a direct change on a feature branch with assertions first). Name every fast test suite to run.
   • ## Conventions that bit us. The repository rules that cost time in this or earlier sessions: forbidden words, line budgets, merge style, the full release checklist with every file to bump, the issues-log rules, the save-state rule. Carry forward the previous handoff's list and add what this session learned; drop nothing unless it is no longer true.
   • Closing reminders after the sections: uncommitted files, background agents still running, a CLI restart owed after a plugin update, files that are local and untracked.