Handoff

Compact the current session into a transient handoff doc so a fresh agent — same user, another agent, another machine, or a teammate — can pick up the work without copy-pasting context by hand.

Invocation Position

/handoff is a side-route skill. It is invoked ad-hoc, not from any default pipeline path.

Use /handoff when:

• a session has run long and the next step is better served by a fresh context window
• you are mid-skill (mid-/execute, mid-/qa, mid-/improve-codebase-architecture) and the existing inter-skill compression artifacts (closing summary, research file, PRD issue, slice issue, PR) do not fit because you are not at a skill boundary
• you are doing exploratory, debugging, or other non-pipeline work where no natural compression artifact exists
• you want to hand off to a teammate, a different agent (Codex, Gemini, another Claude session), or a different machine

Do not use /handoff when:

• a primary pipeline skill is about to print its **Next session:** runtime line — that is the inter-skill compression artifact, and using /handoff alongside it duplicates work and creates two competing handoff records
• the right move is to update an existing durable artifact: a closing summary in /shape, the PRD issue body, a slice issue comment with what was done and what remains, the PR body, or a docs/solutions/ entry. State that belongs in GitHub belongs in GitHub
• the session is trivial (single-question Q&A, single-file edit, copy fix) — a handoff doc would dilute the work, not compress it

/handoff reconnects to the main pipeline by being invoked again — or not — from the fresh session. It produces a transient artifact, not a durable work item.

Process

1. Confirm the next-session focus

If the user passed an argument to /handoff that names a next action (a skill to run, a feature to build, a bug to chase), treat it as the description of what the next session is for. Skip ahead to Step 2.

If no argument was passed, or the argument names no next action ("the work so far", "everything we did"), ask one question — what the next session will be used for — and wait for the answer. Do not present a list of questions.

2. Read existing state — do not duplicate it

Capture pointers to durable state, not copies of its contents. Run the cheap commands first:

• git branch --show-current — current branch
• git log --oneline -10 — recent commits
• git status --short — uncommitted changes, if any
• gh pr view --json number,title,url 2>/dev/null — active PR on this branch, if one exists
• gh issue list --assignee @me --limit 5 --state open — relevant open issues, when applicable
• processes this session started and left running (a dev server, a watcher, an automation browser) — stop each one, or list it in the doc with how to stop it, so the next session does not collide with it

If the work belongs to a pipeline feature, locate the research artifact rather than rereading it:

• archive mode (default): the absolute path the PRD cites (/research Phase 5c states where it is written); check it with sidecar.sh require <path> --from "PRD #<n>", from the bundled references/sidecar.sh, and record a MISSING: line in the doc rather than dropping the pointer
• spike-issue mode: gh issue view <spike-issue-number>

If a PRD or slice issue is in scope, record its number. Reference each of these by path, URL, or issue number — never copy bodies into the handoff doc. Future-you can run gh issue view from the fresh session.

3. Write the doc to a mktemp path

Generate the path with this block, run as one shell. The doc never lives inside the repo working tree.

dir="${TMPDIR:-/tmp}"
HANDOFF="$(mktemp "${dir%/}/handoff-XXXXXX")" && mv "$HANDOFF" "$HANDOFF.md" && HANDOFF="$HANDOFF.md" && echo "$HANDOFF"

The X's sit at the end of the template, with no suffix after them, because that is the one shape BSD and GNU mktemp both fill in; the .md is added by the rename. scripts/test-handoff-mktemp.sh runs this block and pins the result.

Read the path before writing to it (the file exists, empty, after the block). Write the body. Print the path to the user at the end so they can paste it into the next session.

4. Shape the doc body

Follow the plain-language walkthrough shape from docs/writing-for-humans.md (bundled in this skill's references when invoked outside the skills repo). The body should be readable in one pass by someone who has not seen this conversation.

Order:

1. Domain setup — one paragraph. What part of the system or what problem this conversation has been about, in the user's own words.
2. Lede — one sentence. Where the work is right now. Front-loaded. Smart Brevity's Lede: state it before you qualify it.
3. What was tried / what's open — short paragraphs or tight bullets. The specific things that were done, the specific things still open, and any decisions that were taken. Reference durable artifacts by path or URL; never restate their contents.
4. Why it matters — one or two sentences. What this session unlocks or unblocks. Smart Brevity's Why it matters: signpost.

5. Next session — a block in the same shape primary pipeline skills already emit:

   **Next session:** <skill or instruction>
   **Input:** <artifact path, issue or PR number, branch name, or "use the handoff doc above">

6. Suggested skills — one or two /<skill-name> references the fresh session is likely to want, with a one-line reason each. Optional; skip when the next move is obvious from the Next session block.

Revise once before saving. Apply the bar in docs/writing-for-humans.md: strip clutter, cut warm-up, prefer active verbs and concrete nouns, ensure the lede earns the next sentence.

Then confirm three things about the content. Each can be checked; none asks whether the doc reads well to you, which is the question the writer is least able to answer (Step 5 asks someone else).

• Mutable external state was re-checked during this run. A claim about a deploy, a secret, a database row, a live URL, or a test result was checked in this run, or the doc marks it "unverified". A fact recalled from earlier in the session is not checked.
• No pointer leads into session scratch. Apart from the doc itself, nothing the doc points to lives under a session scratchpad or $TMPDIR path, because the next session may not have it. Move the content into the doc, or into a durable home, or drop the pointer.
• Every open decision is marked. An approach the doc suggests is either marked "checked feasible", with what was checked, or "unverified".

5. Cold read (DO-CONFIRM)

A handoff's reader lacks the writer's context by construction, and the writer is the one person who cannot see what is missing from it. So before printing the path, spawn one fresh, read-only sub-agent and give it only the doc's path. Ask it:

• Could you start the Next session step from this doc and the files it points to, without asking the user anything? If not, what would you have to ask?
• Separate facts only the writing session holds (an approach already ruled out, a value never written down, a step that was run) from planning the next skill will do on its own (which functions to add, which migration to write). List only the first kind; the second stays out, because the doc carries pointers, not plans.
• Open each file, issue, or PR the doc points to. Where one contradicts the doc, or is stale against it, say which and how.

Fix the doc for each fact the reader lists. Do not run a second cold read; one pass is the check.

A pointed-to durable artifact that the reader found stale (a plan file, a dossier, an issue body) is not this skill's to edit. List each under a Stale pointers heading in the doc, naming the skill that owns it, and repeat the list in Step 6's message.

Skip the cold read only with a one-line reason written into the doc, for example Cold read skipped: the next step is read-only review of PR #N. A skip with no reason in the doc is a skipped check, not a decision.

6. Print the path and exit

Print the mktemp path, a one-line preview of the lede, and any stale pointers from Step 5. The user picks the path up and pastes it into a fresh session. /handoff does nothing else — it does not auto-invoke another skill, it does not modify any other artifact (stale ones are listed, not edited), it does not commit anything.

Common Rationalizations

Red Flags

• The doc is being written inside the repo working tree (not at a mktemp path).
• The agent is about to git add the handoff doc.
• The doc body restates the PRD, the research artifact, or the PR body instead of linking them.
• The doc is being produced at the natural close of a primary pipeline skill, parallel to that skill's existing **Next session:** line.
• The doc is longer than the source conversation deserves — a one-question Q&A becoming a multi-section handoff is the wrong shape.
• The next-session focus is missing or generic ("continue the work") rather than a specific instruction or skill.
• The path is about to be printed with no cold read run and no skip reason in the doc.
• The agent is about to edit a stale plan file, dossier, or issue body the cold read found, instead of listing it under Stale pointers.

Verification

A run of /handoff is not complete until:

• the doc was written to the .md path Step 3's block printed, outside the repo working tree
• the body references durable artifacts by path, URL, or issue number — not by quoted content
• the body includes a **Next session:** block in the conventional shape
• every process the session left running was stopped or is listed in the doc
• the Step 4 checks hold: mutable external state re-checked or marked "unverified", no pointer into session scratch, every open decision marked
• the Step 5 cold read ran and its facts were fixed in the doc, or the doc states why it was skipped
• the path was printed to the user
• the doc was not staged, committed, or moved inside the repo

Handoff

• Expected input: a long-running or exploratory session that does not sit on a primary pipeline boundary, plus (optionally) an argument describing the next session's focus
• Produces: a transient handoff doc at a mktemp path, referencing durable state rather than copying it, checked by one cold read before the path is printed
• Comes next by default: a fresh session opened by the user, using the doc as its entry point — the fresh session may invoke any skill (often /execute, /qa, or /help) or continue ad-hoc, depending on the captured focus
• Does not invoke: any other skill — /handoff is a pure side-route producing a transient artifact. Its one sub-agent, the Step 5 cold reader, is part of its own procedure