1 added, 1 removed. Audit A to A.
---
name: handoff
description: "Side-route skill for compacting the current session into a transient handoff doc when no pipeline compression artifact fits — mid-skill, exploratory, side-route, or non-pipeline work. Not for routine inter-skill handoffs; use the calling skill's closing summary + **Next session:** line instead."
sources:
primary:
- - "The Design of Everyday Things — Donald A. Norman"
+ - "The Design of Everyday Things — Don Norman"
secondary:
- "Smart Brevity — Jim VandeHei, Mike Allen, Roy Schwartz"
- "On Writing Well — William Zinsser"
---
# 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
| Rationalization | Reality |
|---|---|
| "The session is long, so I should `/handoff` between two primary pipeline skills." | Primary pipeline skills already print `**Next session:**` from their `## Handoff` section. That is the inter-skill compression artifact. `/handoff` is for situations where that artifact does not fit — not a second copy of it. |
| "I'll write the handoff doc inside the repo so I can refer back to it later." | A handoff doc is a transient context-transfer artifact, not durable state. State that belongs durably belongs in GitHub — update the PRD issue, leave a slice issue comment, write a `docs/solutions/` entry. The handoff doc lives at a `mktemp` path on purpose. |
| "The handoff doc should include the full PRD text so the next session has everything." | No. The next session can run `gh issue view <n>` from the doc's reference. Duplicating the PRD makes the doc go stale the moment the issue is edited and bloats context for no benefit. |
| "I'm mid-`/execute` and the work is unfinished — I'll write a handoff doc instead of leaving an issue comment." | `/execute` already prescribes leaving an issue comment with what was done, what remains, and the exact error output. That comment is the durable record. A handoff doc can carry session-level pointers on top of it, but it does not replace the comment. |
| "The argument the user passed is vague, so I'll skip the focus question." | Ask one question. A vague handoff doc earns less reader trust than a short one with a clear focus. |
| "I'll commit the handoff doc to the repo so it survives." | Don't. Surviving the session is not the goal — compacting it is. If the content needs to survive, the right vessel is an issue comment, a PRD body update, or a `docs/solutions/` entry. |
## 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