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.