---
description: Refresh the HANDOFF Brief (doc/handoff/HANDOFF.md) from current session state and regenerate the next-session kickoff prompt. Current-state only — per-ship history lives in doc/shipping-logs/ (written by /kit:ship). Does NOT commit or push; run /kit:handoff first, then /kit:ship so the HANDOFF edit rides the ship payload.
---

# /kit:handoff

Wrap a session: keep `doc/handoff/HANDOFF.md` an accurate **current-state snapshot**, and produce a kickoff prompt the next session can paste in cold.

`doc/handoff/HANDOFF.md` is a **current-state Brief** — it does NOT accumulate per-session "what shipped" writeups. That history lives in `doc/shipping-logs/` (written by `/kit:ship`). Keep HANDOFF lean — if it grows past ~150 lines, the wrong thing is going into it (a cumulative feature list belongs in a roadmap doc; per-ship detail belongs in `doc/shipping-logs/`).

This skill does **NOT commit and does NOT push**. `/kit:ship` does that. The intended order is `/kit:handoff` → `/kit:ship`, so the HANDOFF edit lands inside the slice's ship payload and publishes with it. For a session that won't run `/kit:ship`, see **Edge cases**.

Parse `$ARGUMENTS`:

- (empty) — refresh `doc/handoff/HANDOFF.md` against the current session and regenerate the kickoff prompt.
- **--dry-run** — build the refreshed HANDOFF + kickoff in a fenced preview block, but do NOT write the file. Useful for "what would the handoff look like right now?".
- **--next=&lt;text&gt;** — name what's next explicitly (e.g. `--next="F12 webhook retries"`) instead of inferring it from the session. Drives the kickoff prompt's title + context.

## Preflight

1. `git rev-parse --is-inside-work-tree` — abort if not a git repo.
2. Resolve the **base branch** to diff the session against:
   - `git symbolic-ref refs/remotes/origin/HEAD --short` (strip `origin/`) → the repo's default branch. Fall back to `origin/main` / `origin/master` if unset.
   - Use `git log <base>..HEAD` as "what this session/branch added."
3. Confirm `doc/handoff/` exists. If not, this is the first handoff — create `doc/handoff/HANDOFF.md` from the skeleton in **Step 2** rather than editing.

## Step 1 — Inventory what happened

Survey the session — gather, don't show yet:

- `git log <base>..HEAD --oneline` — what's committed locally this branch.
- `git status --porcelain` + `git diff --stat` — uncommitted work.
- Recent `TaskList` (if present) — completed vs deferred.
- From the conversation: decisions made, scope cuts, schema/migration changes, new env vars, external-service touchpoints, anything paused mid-flight.

Produce a short internal summary (slice/title · what changed · schema/env deltas · deferred items · open threads). This feeds Steps 2–3; do not print it.

## Step 2 — Refresh `doc/handoff/HANDOFF.md`

Update **only** these sections — nothing else belongs in this file:

1. **Intro line** — keep the "refreshed at each `/kit:handoff`" note + the `docs/archive/` pointer (see Archiving).
2. **Where we are** — the one-block current-state status: what's now feature-complete, what's paused, any new external dependency. Tight.
3. **What's next** — the next 1–3 things in priority order. If priorities shifted this session, reflect it.
4. **Open threads** — the short list of genuinely-open items needing attention soon. **Prune anything resolved this session.** Long-horizon "maybe someday" items belong in a deferrals doc, not here.
5. **Kickoff prompt** — Step 3.

Do NOT add: a "What shipped this session" section (→ `doc/shipping-logs/`), a past-sessions log, or a cumulative feature list (→ a roadmap doc).

First-handoff skeleton (when the file doesn't exist yet):

```markdown
---
title: Handoff — Current State
---

# <Project> — Handoff

_Current-state snapshot, refreshed at each session's `/kit:handoff`. Per-ship "what shipped" history lives in `doc/shipping-logs/`. Older handoff content is archived at `docs/archive/`._

## Where we are

<one-block current state>

## What's next

1. <next thing>
2. <…>

## Open threads

- <genuinely-open item>

## Kickoff prompt for the next session

> <generated in Step 3>
```

## Step 3 — Regenerate the kickoff prompt

Replace the "Kickoff prompt for the next session" section at the bottom of `HANDOFF.md`. It must be **specific to whatever's next** (use `--next=` if given), not generic:

```markdown
## Kickoff prompt for the next session

> Starting **<work item / FNN — Title>**. Read `CLAUDE.md`, then `doc/handoff/HANDOFF.md` and the relevant Briefs under `doc/`. {One-paragraph context: what this work is, why now, what infra is already in place.}
>
> Before any code, confirm the design shape:
>
> 1. **Surface.** {Where does this live? Closest precedent in the codebase?}
> 2. **Fields / inputs.** {What does the user/agent provide?}
> 3. **Eligibility.** {When is the action available? State guards?}
> 4. **Data path.** {What writes happen, in what order? What events/logs are emitted?}
> 5. **{Feature-specific question.}**
> 6. **Out of scope / deferrals.** {What are we explicitly NOT building? Trigger to revisit?}
>
> Scope the slice, confirm deferrals, then branch off the default branch. Run `/kit:handoff` then `/kit:ship` at session end.
```

If `What's next` lists multiple candidates, write the kickoff for the most-likely-next and add a one-line note about the alternative.

## Step 4 — Tell the user

Single short message:

1. **Confirm `HANDOFF.md` is updated** — brief recap of the new current-state + what's-next.
2. **Show the kickoff prompt** — copy-paste ready, in a fenced block.
3. **Remind:** start a **new** session for the next slice (one session per feature/branch) and paste the kickoff as the first message.
4. **Suggest `/kit:ship` next** if there's uncommitted work — there will be, at minimum the HANDOFF edit — so the refresh publishes with the slice.

Do NOT commit. Do NOT push. `/kit:ship` does that.

## Archiving (keep HANDOFF lean)

If `HANDOFF.md` exceeds ~150 lines or the "Where we are" block has accumulated many fully-shipped-and-stable bullets:

- Move the stale, no-longer-active content to `docs/archive/HANDOFF-thru-<YYYY-MM>.md` (append to it if it exists).
- Leave a one-line pointer in the intro line.
- The live HANDOFF should read in under a minute. History is recoverable from the archive + `doc/shipping-logs/`; it does not need to live in the active snapshot.

## Edge cases

- **Session shipped code** — `/kit:ship` runs after this and commits the HANDOFF edit along with the slice. The normal path.
- **Design / planning / process session, no `/kit:ship`** — still refresh HANDOFF (decisions made, deferrals identified, new open threads) and the kickoff. Since no ship will run, either make a small `docs:` commit of the HANDOFF change yourself, or tell the user it's uncommitted and unpublished. Do not silently leave it dangling.
- **No changes since base** (pure conversation, no code, no decisions) — don't fabricate updates. Refresh only the kickoff prompt and say "no current-state changes; here's the prompt for next session."
- **Session spanned multiple slices** (rare — violates one-session-per-feature) — each slice already has its own `doc/shipping-logs/` entry from `/kit:ship`; just ensure HANDOFF's current-state reflects all of them.

## Notes for the assistant

- HANDOFF is **current-state only**. The single most common failure is letting it grow into a session journal — that's what `doc/shipping-logs/` is for. When in doubt, cut.
- This skill never pushes; it respects the same unauthorized-push rules as `/kit:ship`. The HANDOFF edit becomes team-visible only when `/kit:ship` pushes it.
- If the repo registers a `handoff` doc category in its file-content-sync config (mapping `doc/handoff/**` to the discussion handler, the same mechanism `/kit:ship` uses for `doc/shipping-logs/**`), the HANDOFF Brief materializes as a Comm Hub comment on push. If not, HANDOFF still works as a local cold-start doc — it just isn't mirrored to the Comm Hub. That category registration is a one-time repo/server config, not this skill's job.
