handover

Handover

Turn everything this session established into one prompt a fresh agent can execute without asking a question.

Authority Boundary

Writing a handover is a documentation act. Produce the prompt file and stop. Do not implement the work it describes, commit it, or push it unless the user separately asks. The next session owns execution.

What a Handover Carries

The receiving agent starts with an empty context window. It sees the repository and the prompt — nothing else. Four classes of knowledge die with this session unless the prompt captures them:

• User-stated constraints: preferences, rejections, and scope limits the user gave in conversation. These are authoritative and unrecoverable from the code.
• Verified findings: facts confirmed this session by reading dependency source, running a command, or fetching documentation — with the evidence that settled them.
• Rejected alternatives: options considered and dropped, with the reason. Without these the next session re-litigates settled decisions or walks into a known dead end.
• Current position: what is done, what is half-done, and what has not started.

Repository state that the next agent can read for itself is not knowledge — it is noise. Point at files instead of transcribing them.

Workflow

1. Re-read the session: Recover the original request, every subsequent user correction, and the decisions each one settled. A later correction overrides an earlier instruction; carry the resolved position, not the debate.
2. Separate instruction from inference: Mark what the user required, what you proposed and they approved, and what you assumed without confirmation. The next agent must know which lines it may revise.
3. Verify before you write: Re-check every path, symbol, command, and version the prompt will name. Stale coordinates are worse than absent ones — they send the next session confidently to the wrong place. Drop or re-derive anything you cannot confirm now.
4. Capture the position: Record completed work with its proof, in-progress work with its exact stopping point, and untouched work. Name the branch and whether the tree is clean.
5. Record the trade-offs: For each real decision, state the choice, the alternatives, and why. For each dead end, state what failed and how it failed, so the next session does not retry it.
6. State the proof contract: Name the commands that must pass before the work is done — normally mise run check and mise run test — and any check that is currently red.
7. Draft as an instruction, not a report: Address the receiving agent in the imperative. It needs orders and context, not a narrative of what you did.
8. Test for self-containment: Read the draft as someone who never saw this session. Every pronoun must resolve, every "as discussed" must be replaced by the substance, every file reference must be a path. Rewrite anything that only makes sense to you.
9. Write the file: Save to .agents/prompts/<YYYY-MM-DD>-<slug>.md and report the path so the user can paste or pipe it into the next session.