Handing over

A session ends. Everything it learned and failed to write down ends with it.

The successor needs to know where things stand, and it must not be misled by a summary that can omit constraints or lag behind the repository. A handover defends both at once, and the two pull against each other.

Write it before you are forced to

Checkpoint while continuity is intact. Recover from observed context pressure or lost task state, not a guessed session lifetime.

At meaningful work boundaries, record decisions, rejected approaches, pending work and verification limits in the owning docs or work items. Keep the handover as pointers to that durable state. Do not wait for a warning to preserve the reasoning needed to recover; the handover itself is an editing task.

Capacity warnings, missing constraints, contradictory decisions and repeated re-discovery are reasons to pause and re-check continuity. Before continuing, re-read the governing instructions, relevant decisions, working-tree state and pending actions. These symptoms call for recovery even without proof that context length caused them.

If relevant work remains and the runtime supports it, compaction can relieve capacity pressure. Preserve durable state first and re-check it afterwards: compaction is not lossless, and a larger window does not guarantee quality. If sufficient room or coherent task state cannot be restored, hand off the unfinished work with explicit unknowns. Use fresh context for unrelated work; resuming a session is not necessarily a fresh-context reset.

Do not create a successor for completed work. For a necessary handoff, identify the unfinished scope and follow agent-concurrency: one writer per working tree, explicit ownership, and the project's admission and retirement rules. Never remove a live session's tree, including your own.

Name the counter before acting on it

When context pressure affects the next step, report the runtime's current occupancy, effective model/tier and counter source if available, including any response reserve relevant to the reading. If unavailable, say so rather than manufacturing a count or percentage.

Do not substitute cumulative session or billed usage, transcript/corpus size estimates, or advertised capacity for current active context. Routine commits and pushes do not require a token report. Budget for read-in by measuring its actual prompt boundary separately from the corpus; label estimates as estimates.

No universal restart count or percentage is established by the reviewed evidence. Do not replace the old cutoff with another guess. A quantitative local policy needs a defined counter, runtime/model/tier and comparable outcomes, including recovery cost. The public sources and limits are in CONTEXT-HANDOFF-EVIDENCE.md; they are not measurements of a private desktop runtime.

Durable reasoning makes recovery possible, not cost-free. If handing off needs reconstruction, preserve what is missing before leaving it to another session.

It is a file in the repository, not a message

A handover passed session-to-session in a kickoff prompt is one lost message away from gone.

A file is read by whoever turns up next, survives a session nobody resumed, and shows up in a diff when it goes stale. A message has none of those properties, and the handover is the most droppable artefact a project has.

It is the one document allowed to be wrong

State this inside the file, in the file's own voice:

Do not trust this file over the docs. It is one session's summary of where things stood when it stopped. Current contracts and governing instructions own the requirements; this note does not. Re-check disagreements against their evidence and update the stale summary. A document is not necessarily gated.

That sentence is what makes the file safe to write quickly, and what stops a successor building on a stale summary. Without it a handover accumulates authority it never earned, and the reasoned documents stop being read at all.

The corollary is a rule for the writer:

Anything load-bearing goes in a doc first, and the handover links to it. A decision reachable only from the handover is in the wrong place.

Keep three routes distinct: current contracts for accepted requirements, existing work items for proposed changes and unfinished checks, and accessible history for decisions and reversals. durable-project-memory owns that lifecycle. Do not turn the handover into another current specification or a second task queue.

Say how to re-check; do not quote what rots

Every status figure in a handover has an expiry date. Branch names, commit counts, open-item counts and working-tree status can all become false within a day while still reading as current.

Give the command instead of the answer:

A command is self-dating. It cannot report last week's state.

Say what you did not verify

A successor assumes anything unmentioned was done.

Give this a heading of its own so it cannot be quietly omitted, and state the boundary of what was checked rather than the effort spent:

• Not "tested in a browser", but which browser, at which widths, against which environment, and what was never opened.
• Not "the gate passes" but what the gate does not cover: network fetches, data rebuilds, real rendering, migrations.
• Anything you could not do because you were sandboxed, firewalled, or missing credentials. Hand that check back explicitly rather than concluding the suite was sufficient. See the verify-in-the-real-thing skill.

With several agents reading the file at once, an unstated omission is assumed done in parallel.

If delivery is in scope, separate the boundaries rather than writing "shipped": reviewed head, gated head, merged revision, deployment run, and observed runtime identity. Record an expected refusal, such as an exact-head mismatch, as a safety outcome rather than collapsing it into "failed."

Settle what is open before you go

Ask every open design question while you still have the context to argue about it. A question left for the successor is one it must answer with less of the reasoning than you have.

What cannot be settled does not go in the handover as a paragraph. It goes in its own file, with the recommendation and the reasoning, so the next agent inherits an argument rather than a blank and can claim it, which a paragraph cannot be. See the agent-concurrency skill for the claim protocol and the four states.

Finish by pushing

Work that is done is committed and pushed before the session ends. Not staged, not left modified, not described in the handover as "ready to commit".

A session that stops with uncommitted work has not finished it. It has moved the work somewhere less safe than where it started.

A dirty working tree is invisible to everyone except the tree it sits in, and in a shared checkout it belongs to whoever commits next. If work cannot land because it is unfinished or a decision is outstanding, commit it to a branch and say so in the handover. An unpushed branch is recoverable; a dirty tree is not.

When a person is driving the session, ask before committing on their behalf, then commit and push what they approve rather than leaving it for them.

Keeping the file honest

Four rules, and they belong inside the handover as its last section so whoever edits it next reads them:

• Update it before you hand off, not after you are asked. It is worth exactly as much as its last edit.
• Put anything load-bearing in a doc first.
• Settle open questions while you still have the context to argue about them.
• State what you did not verify.

Structure

assets/HANDOVER-template.md is the shape, ready to copy. In outline:

1. A pointer to the instructions file and the docs, and the do not trust this over the docs warning.
2. Where things stand: commands to run, not figures.
3. What is open: a pointer to the open items, not a list.
4. Who continues this, if anybody, and where their work will appear. If nobody was created, say so and why: silence reads as a successor that exists, and the project waits for an agent nobody made.
5. What was not verified.
6. Delivery identity, when the work was meant to land or deploy: pull request and base, reviewed/gated head, merged revision, exact deployment run, and observed build identity. Write "not observed" rather than inferring one boundary from another.
7. Where the reasoning lives: links only.
8. Keeping this file honest.

Write the prose plainly: unslop lists the habits that pad a handover without adding a fact.

What a handover is not

• It is not a substitute for the docs. If it is the only place something is explained, move it.
• It is not a plan for the successor. Handing over a phase the next session did not choose wastes the one advantage it has, which is reading the current state with fresh context. Point at what is open and let it pick.
• It is not a changelog. git log already exists and does not go stale.
• It is not a place to be reassuring. The value is concentrated in the parts that admit something.

Why each of these is the rule, and the failures behind them, is in references/REASONING.md. Read it when arguing about one of them, not to apply them.