---
name: session_handoff_docs
description: "Write a session handoff document so a fresh agent can pick up work with zero questions asked. Use when a work session is ending, context is getting heavy, work moves to another agent or subagent, or you are asked to brief someone taking over."
---

# Session Handoff Docs

## Purpose

A handoff doc is the state capture between an agent that had the context and one that does not. The receiver cannot ask what you meant, so the document has to stand on its own. This skill produces a short, structured file covering three things: the state of the work, every open loop, and the single next action stated so clearly that a fresh agent can act on it without guessing.

This is for live work moving between owners, not for postmortems after the fact. If the work is done and you are only summarizing what happened, that is a retrospective, and this skill is not for it.

## Workflow

**1. Decide when to write one.** Write a handoff at any of these points:
- The session is ending and work continues later.
- Context is past roughly 60% and a long stretch of work remains. Hand off early, while the model is still sharp, not at the wall where compression already degrades quality.
- Work is moving to a subagent, another agent, or a different model/tool.
- A task is blocked and someone else will resume it.

**2. Gather the load-bearing facts only.** Preserve: current objective, what is done, active subtasks, key decisions and reversals (with the reason, not just the outcome), what was tried and failed (the most expensive failure is the receiver retrying a dead end nobody mentioned), unresolved errors with the current hypothesis, blockers, and exact paths of artifacts, logs, and files that matter. Cut: long narrative history, re-summaries of resolved steps, logs that regenerate cheaply, and anything already documented on disk elsewhere. Never record secrets, tokens, or credentials.

**3. Write the five sections, in this order.** Each section answers one question. Keep the whole document under about 300 words of prose; bullets over paragraphs.
- **Situation:** one or two lines. What is the work and where does it stand right now? A reader who stops here should know whether this is urgent and what the headline is.
- **Background:** only the context that changes what the receiver does next. Decisions already made that should not be re-litigated, approaches tried and ruled out, constraints in force. Include by relevance, not by completeness.
- **Assessment:** your honest read. What do you believe is going on, what is the current hypothesis on anything unresolved, and what risks is the receiver inheriting? Opinion is allowed here, labeled as opinion.
- **Recommendation (the next action):** one primary next step, written as a verb phrase with enough detail to execute: what to do, on which file or resource, and what "done" looks like. Secondary follow-ups after that, short.
- **Where things live:** exact file paths, document names, branch, last known good commit or state marker if applicable, and how to verify the current state before acting (one command or check).

**4. Run the read-back test.** Read the document as if you know nothing about the work. Ask: would a fresh agent know exactly what to do first, what not to retry, and where to look? If not, the missing sentence is usually in Background or the next action is vague. Fix it now.

**5. File it and mark it active.** Save to a dated, descriptive path like `handoffs/2026-10-06-deploy-fix.md`. If a previous handoff exists for the same task, mark the old one superseded in its header and point to the new file. Exactly one active handoff per task; stale ones are archived, never left ambiguous.

## Output Contract

Every handoff document this skill produces:
- Has all five sections, in order, each answering its section's question in bullets.
- States the next action as an executable verb phrase (do this, on this, done looks like that), not as a topic ("look into the deploy").
- Names at least one dead end or ruled-out approach if any exist.
- Lists exact paths for every artifact the receiver needs; no "it's in the repo somewhere."
- Contains no secrets, tokens, or credentials.
- Stays under roughly 300 words of prose, excluding the file-path list.
- Is written to a dated file, and any prior handoff for the same task is marked superseded.

A worked example is in `references/worked-example.md`. A copy-ready template is in `assets/handoff-template.md`.

## Operating Rules

1. Accuracy is non-negotiable. Every factual claim (state, error text, what was tried, commit ids) comes from this session's actual work or a verified source. If you are unsure whether something happened, say so or leave it out. Never invent numbers, quotes, or events.
2. Write the why, not just the what. "Chose X" is useless without "because Y failed at Z." The receiver will reopen settled questions otherwise.
3. One next action leads. A handoff with five equally-weighted suggestions is a status report, not a handoff. Order the rest behind the primary step.
4. Never hand off speculation as state. If something is a hypothesis, label it. The read-back test catches this: if a sentence could be misread as fact, it will be.
5. Keep handoffs boring. This is state capture, not a report. Plain language, no filler, no motivational framing. If a sentence would not change what the receiver does, cut it.