handoff

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      # the feature slug, or null for cross-feature work
git_base: 3451766     # `git rev-parse --short HEAD` at write time
status: active        # active when written; /resume flips it to consumed
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.