handover

name	handover
description	Save session progress to a HANDOFF markdown and print a copy-pasteable pickup prompt. Use before `/clear`, when context is getting heavy, or when pausing work. Works for both repo-scoped and non-repo sessions. Produces a structured snapshot the next session can consume via the `pickup` skill.

handover

Produce a handover document for this Claude Code session so work can resume cleanly after /clear or in a new session.

Where HANDOFF.md goes

Decide location by checking the session's working directory:

1. Inside a git repo (git rev-parse --show-toplevel succeeds): write to <repo_root>/HANDOFF.md. This keeps repo-scoped work next to the code.

2. Not in a git repo (home dir, ad-hoc session, etc.): write to ~/.claude/handovers/<slug>.md where:

   • <slug> = user-supplied label from the invocation argument (e.g. /handover memory-cleanup → memory-cleanup.md), OR
   • <slug> = auto-generated from session content: kebab-case topic + date suffix (e.g. claude-mem-research-2026-04-22.md).
   • Create ~/.claude/handovers/ if it doesn't exist.
   • Do not overwrite silently in this dir — if a file with the same slug exists, append -2, -3, etc.

Always print the absolute path of the file you wrote.

Template

Write the file using these exact section headers — the pickup skill parses them:

# HANDOFF — <short task label> (<YYYY-MM-DD HH:MM>)

_Scope: <`repo:<name>` or `adhoc` (non-repo session)>_

## Goal
<One sentence: what this session was trying to accomplish.>

## Status
<What's done, what's in progress, what's not started. Be specific. No generalities like "made progress on X".>

## Files touched
- `path/to/file.ext` — <one-line reason>
- ...
(For ad-hoc sessions, list files across repos with absolute paths. For repo sessions, prefer repo-relative paths.)

## Key decisions
- Chose <X> over <Y> because <Z>.
- ...

## Open threads / blockers
- <Unresolved question, failing test, external dependency, etc.>

## Next step
<The literal next action. One specific actionable sentence. Not a list.>

## Don't do
- <Dead end already ruled out or user correction — so the next session doesn't retry it.>

Rules

1. Secrets exclusion. No credentials, tokens, API keys, .env/.ssh/wallet content in HANDOFF.md.
2. Disk > chat. The summary goes in the file, not in chat.
3. Terse. Bullets over prose. Specifics over generalities.
4. Thin handovers are fine. If little happened, write it anyway — a skeleton is more useful than nothing.
5. Repo handovers overwrite HANDOFF.md in place. Ad-hoc handovers never overwrite — they suffix on collision.

Output to the user

After writing the file, print exactly this block and nothing else:

HANDOFF written: <absolute path>

Next: /clear, then /pickup <slug>

Where <slug> is the ad-hoc filename without the .md extension. For repo handovers (written to <repo_root>/HANDOFF.md), /pickup with no argument works — the pickup skill auto-detects ./HANDOFF.md from CWD.

The pickup skill does the reading, parsing, file re-reads (conditional on modification), and resumption from Next step — don't duplicate any of that guidance here. No paste-ready prompt needed; /pickup <slug> triggers the behavior.

No "here's what we did", no "let me know if...". Just the confirmation line and the Next command.