Write a Handoff Doc (context-saving for /clear)

Long work often spans many sessions on one thing. The chat fills with the journey (debugging, dead ends, retries) which is almost all token-waste once the work lands. This skill captures the destination — current state + what's left — into a short doc, so the user can /clear and the next chat resumes from the doc, not the transcript.

Where handoff docs go

• Folder: a handoffs/ folder — in the current git repo root if we're in one, else the home directory. Override with the HANDOFF_DIR env var.

  BASE="$(git rev-parse --show-toplevel 2>/dev/null || echo "$HOME")"
  DIR="${HANDOFF_DIR:-$BASE/handoffs}"
  mkdir -p "$DIR"

• Untracked by default. These are transient context, not shipped docs. If you're in a git repo, add handoffs/ to .gitignore so they don't get committed. The destination doc a handoff points to (a README / plan / spec) stays tracked wherever it already lives.
• Naming: <Project>-<topic>-Handoff-<YYYY-MM-DD>.md (e.g. Auth-Migration-Session-Cookies-Handoff-2026-07-03.md). One per session/topic; don't overwrite an older one — use a new date. Use today's date from the Claude Code environment's currentDate.

The one rule: destination, not journey

The reader is a fresh agent with zero context. Give it where the work IS and what's LEFT, anchored to the destination doc — the project's README, plan, or spec (put a pointer to it at the very top if one exists). Cut the blow-by-blow: no "first I tried X, then Y." Keep failed approaches only as one-line "don't re-try this because…" warnings.

Template

# <Project> — <topic> Handoff (<YYYY-MM-DD>)

> **DESTINATION DOC (read FIRST):** `<path to the README / plan / spec, if any>`. This handoff is the
> bridge from the work NOW to that destination — state + remaining work, not a journey log.

## Subject
- What this is: the feature/bug/task, the repo + branch, key files, current state.
- **Status now:** committed? pushed? deployed? (say plainly — often UNCOMMITTED).

## DONE & working (build on these)
- Bullet the changes that are in and working, with the file + the WHY (one line each).

## BROKEN / UNVALIDATED / MISSING  ← the heart of the doc
- What's not proven yet and the exact next step to prove it (the command to run, the thing to check).
- Known baselines/numbers/error messages worth keeping.

## REVERTED / deferred (do NOT blindly re-add)
- What was backed out and the reason, so the next agent doesn't repeat the mistake.

## Files touched (uncommitted)
- Path list so the next agent / a future commit knows the blast radius.

## Build / run / test workflow specifics
- The exact commands for THIS work: how to build, run, test, and see the result. Branch, env vars,
  any setup the next agent needs so they don't rediscover it.

## Next-session task list (scoped)
1. … 2. … 3. …  (ordered and concrete; mark anything that's someone else's domain to unblock)

Steps

1. Read $ARGUMENTS (a topic label) and the conversation → identify the project/topic, its current state, and what's left.
2. Resolve $DIR (above) and pick the dated filename.
3. Fill the template faithfully — destination not journey; be honest about what's unproven. Don't inflate "unvalidated" into "done".
4. Write the doc to $DIR/<name>.md with the Write tool.
5. Report the path and tell the user it's safe to /clear — the next chat should read this doc (and the destination doc it points to) first.

Rules

• Doc-only. Never bumps versions, commits, deploys, or changes code — it only writes the handoff.
• Destination, not journey — the single most important rule. A handoff that re-tells the debugging story has failed; one that says "here's where it is, here's the next probe" has succeeded.
• Faithful — represent uncertainty and open bugs honestly; the next agent trusts this doc.

Companion: auto-load-on-/clear hook (optional)

No skill or tool can make /clear itself seed a message — that's a hard Claude Code platform limit (/clear is user-typed only, never programmatic, and always starts empty). The closest substitute is a SessionStart hook matching clear that fires right after /clear and injects a pointer to the newest relevant handoff doc as context, so the fresh session reads it before doing anything else, without waiting for the user to run /start.

Sketch — a script that prints the newest handoff for the current branch, wired in settings.json under hooks.SessionStart with matcher: "clear":

#!/usr/bin/env bash
# ~/.claude/hooks/handoff-on-clear.sh — no-ops silently outside a git repo.
BRANCH="$(git rev-parse --abbrev-ref HEAD 2>/dev/null)" || exit 0
BASE="$(git rev-parse --show-toplevel 2>/dev/null || echo "$HOME")"
DIR="${HANDOFF_DIR:-$BASE/handoffs}"   # same default as the skill above
[ -d "$DIR" ] || exit 0
# best-effort: prefer a handoff whose name matches the branch's topic, else the newest overall
DOC="$(ls -t "$DIR"/*"${BRANCH##*/}"*.md 2>/dev/null | head -1)"
[ -n "$DOC" ] || DOC="$(ls -t "$DIR"/*.md 2>/dev/null | head -1)"
[ -n "$DOC" ] && echo "Resuming? Read the handoff first: $DOC (confirm it matches the user's intent)."

It's a nudge, not authority — the injected text should tell the resuming chat to confirm the picked handoff actually matches what the user wants before proceeding. /start remains the authoritative orientation step (clean-tree check, contamination flag, sync with origin); the hook just removes the "remember to type /start" step for the common case.