Handoff

---
name: handoff
description: Produce a structured handoff document before any context switch, topic change, or when a fresh model would improve outputs. Run autonomously — do not wait to be asked. Trigger when: conversation topic shifts significantly, context window is getting long, repeated mistakes suggest context confusion, a complete unit of work just finished, or the user opens a new project. Save to ~/.claude/handoffs/ with a timestamped filename.
argument-hint: "What will the next session focus on? (optional)"
tags: [intent:handoff, intent:context-switch, intent:document, type:skill]
---

# Handoff

Produce a handoff document so a fresh agent can continue without losing context. Run this **before** the context switch happens, not after.

## When to Run Autonomously

Run without being asked when any of these are true:
- The conversation has been long and covered multiple distinct topics
- You've made repeated mistakes or lost track of earlier constraints — a fresh model would do better
- The user is about to open a different project or codebase
- A complete unit of work just finished (feature shipped, bug fixed, research done)
- The topic is about to shift significantly from what's been discussed
- The user starts a new session: check `~/.claude/handoffs/` for the most recent doc and resume from it

## Save Location

Save to `~/.claude/handoffs/handoff-YYYY-MM-DD-HH-MM.md` using the current timestamp.

After saving, you MUST do both:
1. Tell the user: `Handoff saved to ~/.claude/handoffs/handoff-[timestamp].md`.
2. **Output the full Resume prompt as a fenced, copy-paste code block directly in the chat** — never make the user open the file to find it. A `PostToolUse` hook (`emit-resume-prompt.py`) also prints it automatically as a backstop, but you must surface it yourself too.

## Document Structure

```
# Handoff — [date]

## What we were working on
[1–3 sentences. The actual goal, not the task list.]

## Current state
[What's done, what's in progress, what's blocked. Be specific — file paths, function names, error messages.]

## Key decisions made
[Decisions and the reasoning behind them. What was tried and rejected, and why.]

## Open questions / next steps
[What needs to happen next. Ordered by priority.]

## Suggested skills
[Which mattpocock/skills the next agent should invoke, and when.]

## Resume prompt
---
Continue from handoff: ~/.claude/handoffs/handoff-[timestamp].md

[2–3 sentence summary the user can paste at the start of a new session to orient the fresh model instantly]
---
```

## Rules

- Do not duplicate content already in files, commits, or PRDs — reference by path instead
- Check whether this session wrote anything meant to persist to a temp/scratchpad location (e.g. a scratchpad dir, `/tmp`) — these are session-scoped and vanish in a new session with no error. If so, name its durable destination explicitly in the handoff rather than just noting the loss risk. Confirmed 2026-07-07: a benchmark script + logs left in a session scratchpad would have been silently lost otherwise.
- Same check applies to substantial content that never touched a file at all — e.g. a forked/background agent's full findings (a ranked review list, a multi-point analysis) relayed only as a chat message. If it's referenced as "see transcript" or "see the final assistant message" instead of a path, that's the scratchpad risk in a different shape: it's one context-compression away from gone. Write it to a durable file (a PR comment, `~/.claude/outbox/`, a scratch note) as part of producing the handoff, don't just flag the risk. Confirmed 2026-09-14: a forked `/code-review` agent's full 10-finding PR review existed only in-transcript at handoff time.
- Redact API keys, passwords, PII
- The resume prompt must be self-contained — the next agent should be able to read it cold and know exactly where to start
- If the user passed an argument describing the next session's focus, tailor the next steps and suggested skills sections to that goal
- Keep the whole document under 150 lines — compress aggressively, reference don't repeat

## On Resume

When starting a new session, check `~/.claude/handoffs/` for the most recent file. If one exists and is recent (within 7 days), read it and use it to restore context before doing anything else.

**Before redoing a handoff's next steps, check whether the session that wrote it is still alive** — especially when resuming on a different machine (laptop died, switched hosts). A session left running on another node (e.g. in a mac-mini Terminal) may already have finished or be mid-way through those steps, so the handoff is stale by construction. Check live state first (PR/merge status, that machine's newest `~/.claude/projects/*/<session>.jsonl`, running `claude` processes). If it's still running, don't take over work in the same repo — two agents editing `~/.agents` concurrently collide; hand the stop-or-let-finish decision to Gil. Works well when the prior session's host is reachable; if it isn't, say the state is unknown rather than assuming it's dead. Confirmed 2026-10-06: after the laptop died, the "lost" session was still running on the mac-mini and had already merged everything the handoff listed as next steps.