| name | handoff |
| description | Compact the current conversation into a handoff document for another agent to pick up. Use before /clear, when context is nearly full, or to checkpoint a long multi-session task. |
| argument-hint | What will the next session be used for? |
Write a minimal recoverable snapshot so the next session can continue from the current node by reading this one file. This is not a conversation summary — extract current state, key decisions, and next actions. Discard exploration; preserve decisions.
Where to save
Per the layout in the ship / to-issues skills' ARTIFACT-FORMAT.md:
- Feature-scoped work →
.scratch/<feat>/handoff.md (rolling — overwrite in place each time; git keeps history). Lives next to that feature's PRD and issues so it never gets lost.
- Cross-feature work →
.scratch/handoff.md (a single rolling file at the .scratch/ root).
Do not use the OS temp directory — it gets cleared between sessions. If not inside a git repo, fall back to the working directory root.
Every handoff carries YAML frontmatter:
---
type: handoff
feature: balance
git_base: 3451766
status: active
date: 2026-06-18
---
What not to duplicate
Content already captured elsewhere (PRDs, plans, ADRs, issues, commits, diffs) — reference by path or URL, do not copy the body.
Redact
Remove any sensitive information: API keys, passwords, tokens, PII.
Output structure (6 fixed sections)
# Handoff: <topic> (<date>)
## 1. 当前状态
Where we are + key artifact paths and their status. One sentence that tells someone "how far we got".
## 2. 基线
git HEAD (commit hash), working directory cleanliness, key file list relevant to this work.
If this work changed the **shape** of a module (moved a seam, introduced/removed an invariant, altered
how things wire up), the `CODEBASE.md` section for that area is now stale — refresh it via `/zoom-out`
before handing off, or note here that it needs refreshing, so the next session's session-start load
(which compares each section's `git_base` to HEAD) hands over a map aligned with the code, not one a
commit behind. Skip this if the work touched no structure — don't run `/zoom-out` for its own sake.
## 3. 下一步分叉
Candidate options for the user / next session to decide (A / B / C) with tradeoffs. If the path is already decided, state the next concrete step.
## 4. 关键口径清单 ⭐
Decisions and invariants that must survive across sessions. Each entry includes a "why".
This is the core value of the document — exploration can be discarded, decisions cannot.
- Decision: … | Why: …
- Invariant: … | Why: …
## 5. 开机动作序列
First ordered actions after /clear (which files to read, which command to run, what to confirm first).
## 6. 明确不写的
What was actively discarded (dead-end explorations, failed approaches) — let the user do a final scan to confirm nothing critical was dropped.
## Suggested skills
Skills appropriate for the next session (e.g. `/tdd`, `/diagnose`, `/grill-with-docs`), one sentence each on why.
Section 4 is the core. If the user passed arguments, treat them as the focus of the next session and tailor the document accordingly.
