Handoff

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, treat it as the description of what the next session is for. Skip ahead to Step 2.

If no argument was passed, 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

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

• archive mode (default): ~/.claude/research/<repo-slug>/<feature-slug>-<YYYY-MM-DD>.md
• 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

The path is generated by mktemp -t handoff-XXXXXX.md. The doc never lives inside the repo working tree.

Read the path before writing to it (the file exists, empty, after mktemp). 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. The dogfooding test: would you, returning cold in six months, understand what was done and what's next? If not, revise.

5. Print the path and exit

Print the mktemp path and a one-line preview of the lede. 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, 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.

Verification

A run of /handoff is not complete until:

• the doc was written to a mktemp -t handoff-XXXXXX.md path, 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
• 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
• 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