session-handoff

Session Handoff

Produce a repeatable end-of-session summary so the user can /clear and start a fresh agent without losing continuity. The next agent should be able to pick up by reading this document and the files it points to, in the order it declares — the handoff is the entry point to the chain, not a replacement for it.

This is a context-handoff artifact, not a status report or a retrospective. The audience is a future instance of you. Capture intent and reasoning, not implementation — anything the next agent can recover in seconds from the diff, the code, or the file itself doesn't belong here.

When to invoke

User says: "session handoff", "wrap up session", "hand off", "handoff summary", "let's wrap up", "summarize before I clear", or any near-equivalent. Also invoke proactively if the user says they're about to /clear without having run it yet.

How to produce the handoff

1. Review the whole session, not just the last few turns. If something was compacted or truncated before this instruction ran, you can't recover it — note that under Open Questions instead of guessing or inventing it.
2. Pull state from what you actually did. These are the categories to sweep; the tool that produces each one varies by runtime, so capture the category even when the named tool doesn't exist here:
   • Plan or spec file that drove the session (in Claude Code, check ~/.claude/plans/ — %USERPROFILE%\.claude\plans\ on Windows — if one was mentioned).
   • Unfinished task state — in-progress or pending items from whatever task tracker was in use (TodoWrite, if present).
   • Long-lived processes you started, and the handle the runtime uses to address them (shell ID, terminal ID, PID). The handle is load-bearing: without it the process is orphaned and unkillable by the next agent. Record the kill command in the same form the next agent will need to type.
   • Files created or modified — list what you tracked as you went.
   • Memory or vault files written or updated (in Claude Code, ~/.claude/projects/<project>/memory/).
   • Decisions and why, knowledge discovered, assumptions made, risks/issues found, constraints stated.
   • Unresolved questions — yours that never got a clear answer, or the user's that got deflected.
3. Locate the prior handoff, if any, and declare precedence. List docs/handoffs/ (or the equivalent output directory) and take the most recent file for this thread of work. Record its path in the Continues from: line — see the Output template. Reading it is optional; linking it is not. Without the link, the next agent has no way to know the chain exists or that anything in it is still load-bearing. The link alone is not enough: append which document wins on conflict, because newer does not automatically mean authoritative — a detailed architecture record can outrank the summary that points at it. Use one of: authoritative for <scope> (read it before acting in that area), superseded by this document, or no conflicts. If the prior handoff is authoritative for anything, it is also the Plan file under Key Files; don't state precedence in one slot and leave the other silent.
4. Verification boundary. git status, git diff --stat, and git rev-parse --short HEAD are fine to confirm what actually changed and anchor the handoff to a commit; listing the handoffs directory is fine for step 3. Don't run git log, repo-wide sweeps, or grep to rediscover what you already know you touched — synthesize from what you tracked while working. If you didn't track something, say so; don't excavate or invent it after the fact.
5. Precision-claims rule. Don't state a specific file path, line number, numeric value, or other precise detail unless you actually observed it this session (via a read, edit, diff, calibration run, test output, or your own tool output). This includes numbers pulled from tables or test results — a specific score, threshold, or before/after value is just as much a precision claim as a line number. It also applies to causal/historical claims (e.g. "X was 0.0, changed to Y this session") — don't assert a change happened this session unless you observed the before-state yourself, not just the current state. If you're recalling, inferring, or unsure, say so explicitly — "exact location not re-verified this session," "approximate," "per earlier handoff, unconfirmed" — rather than stating it as if confirmed. The next agent cannot distinguish a verified specific from a confident guess and will trust whatever you write; a vague-but-honest pointer beats a precise-sounding one that's wrong.
6. Self-consistency pass, before finalizing. Reread Architecture Changes, Decisions & Rationale, Key Files, and Assumptions (and any other sections describing the same system or sequence) against each other. They describe the same facts from different angles and must agree on ordering, naming, and file locations. Every fix-claim in Decisions & Rationale must carry a matching confidence tag in Assumptions — which is why Assumptions is conditionally required, not situational (see Section model). A fix-claim with no matching tag is itself a signal to verify before output, not after. Fix any contradiction, or flag it explicitly under Open Questions — never ship two sections of the same handoff that disagree.
7. Be concise. Bullets over prose. Include only what's lost when context clears, not what's recoverable from the diff or code. An 8-hour session does not justify a 3,000-word handoff — it justifies a dense one. See Calibrating density below.
8. Strip environment-specific markup before saving. Citation tokens, source-reference markers, UI artifacts, and any other runtime-injected syntax must not survive into the file. They render as noise or as a broken reference in a different agent's environment, and a next agent may read one as a real pointer. Paths, code, and commands stay; anything the current interface injected around them goes.
9. Save the document per Output delivery below. Never update memory from this skill.