git:20261018.fb197e3 to git:20261018.119e390

---

name: handoff

description: Use when a session's context is getting long or degrading and you need a detailed, self-contained summary to manually paste into a fresh session (or hand to another machine/tool/teammate). For a short durable fact instead, write it to the persistent memory directory (auto-loaded via MEMORY.md).

allowed-tools: Bash, Read

metadata:

category: claude-config

---

# Handoff

## Overview

Produce a detailed, self-contained context summary that lets work continue in a brand-new session with no access to this one.

By default, print the output to chat for the user to copy and paste.

## When to Use

- The current context is long and answer quality is degrading.

- You want to start fresh while preserving essential context.

- The context window is approaching capacity.

- You need to carry context to another machine, tool, or teammate.

**Not this skill:** a short durable fact for future sessions → write a memory file in the persistent memory directory and index it in `MEMORY.md` (auto-loaded each session). Never write memory files from `handoff` — the two channels serve different lifetimes.

**Handoff-first policy:** if you run a PreCompact hook that intercepts the first auto-compact of a session (this plugin ships none), its interception message makes this skill the first option: print the handoff immediately and tell the user to `/clear` and paste it into the fresh session. Only if the user chooses to keep the session does the next auto-compact proceed normally.

If the session has no meaningful work to preserve, say so and stop.

## The Gate — should this be a handoff at all?

Ordered tree, run before producing anything; first yes wins.

Every move except Continue trades the session — a primary source — for a summary of it, so rule out the cheap options first.

(Adapted from mattpocock/skills `PHASE-BOUNDARIES.md`; `/compact` drops out as a rung here because compaction is automated and its pressure is visible in the statusline.)

1. **Can the session just continue?** The next phase needs this phase's reasoning verbatim, or there is comfortable context left. Continue costs nothing and loses nothing.

2. **Is the context irrelevant to what comes next?** Then recommend `/clear` and stop — nothing worth carrying, and the old session stays resumable. Clearing a _relevant_ context is the one-way mistake: the why behind the work doesn't come back from reading the diff.

3. **Is the remaining work a tightly-scoped AFK task?** Send it to a subagent and leave this session untouched — no handoff needed.

4. **Is something actually travelling?** A handoff earns its lossiness only when context must cross a boundary: a new harness or tool, a new machine or directory, a teammate, or a side task forked mid-phase. That list is the whole clause.

If nothing travels but the context is degrading anyway, that is the handoff-first case: hand off and `/clear` beats letting auto-compact flatten the decisions.

If a hook triggered this — a PreCompact interception, or a context-threshold nudge — the gate is already answered: skip straight to Steps.

Make the call at a phase boundary ("ok, we're done with that"), never mid-phase.

## File Mode

2. Make the first line exactly `cwd: <absolute project root>`. Nothing here requires that line, but it is what a SessionStart pickup hook would grep to route the file to the right project, and writing it costs nothing if you add one later.

3. Add a `NEXT MISSION` section containing one short paragraph that tells the successor session what to do first, followed by the standard template below.

4. Tell the user the file path and recommend `/clear` or a new session. Paste the file in yourself, or wire a SessionStart hook that surfaces anything in `~/.claude/handoffs/` whose `cwd:` matches the project and archives it once picked up.

Never write a handoff file without one of the triggers above.

Never commit handoff files.

## Steps

1. **Gather concrete data.** The full conversation and current TODO state are already in your context — use them directly (there is no `session_read`/`todoread` tool in Claude Code). For file changes, run:

- `git diff --stat HEAD~10..HEAD` — recent changes

- `git status --porcelain` — uncommitted changes

2. **Extract** from the conversation: exact user wording, work completed, decisions, files touched, constraints/preferences established.

3. **Format** using the template below and deliver it through the selected mode.

Write in first person ("I did...", "I told you...").

Capture USER REQUESTS and EXPLICIT CONSTRAINTS verbatim — do not paraphrase or invent them.

## Output Template

```plaintext

HANDOFF CONTEXT

===============

USER REQUESTS (AS-IS)

---------------------

- [Exact verbatim user requests - NOT paraphrased]

GOAL

----

[One sentence describing what should be done next]

WORK COMPLETED

--------------

- [First person bullet points of what was done]

- [Include specific file paths when relevant]

- [Note key implementation decisions]

CURRENT STATE

-------------

- [Current state of the codebase or task]

- [Build/test status if applicable]

- [Any environment or configuration state]

PENDING TASKS

-------------

- [Tasks planned but not completed; next logical steps; blockers]

- [Include current TODO state]

KEY FILES

---------

- [path/to/file] - [brief role description]

(Maximum 10 files, prioritized by importance; include files from git diff/status)

IMPORTANT DECISIONS

-------------------

- [Technical decisions made and why; trade-offs; conventions established]

EXPLICIT CONSTRAINTS

--------------------

- [Verbatim constraints only - from the user or existing CLAUDE.md/AGENTS.md]

- If none, write: None

CONTEXT FOR CONTINUATION

------------------------

- [What the next session needs to know; warnings/gotchas; doc references]

- Before acting on any status recorded above (tracker, review, store or console, inbox), re-read its source: this handoff records what the writing session believed, and that status may have changed since.

```

The last line of CONTEXT FOR CONTINUATION is fixed text: keep it in every handoff, because the receiving session sees only the handoff and never this skill.

## Format Rules

- Plain text with dash bullets — no `#` markdown headers, no bold/italic, no code fences inside the content (so it pastes cleanly as one message).

- Workspace-relative file paths.

- Pick a length proportional to complexity; include only what matters for continuation.

- USER REQUESTS (AS-IS) and EXPLICIT CONSTRAINTS are verbatim only.

- Never include secrets (API keys, credentials, tokens).

- Max 10 files in KEY FILES. GOAL is one sentence.

## Continuation Instructions

For chat output, tell the user:

```plaintext

TO CONTINUE IN A NEW SESSION:

1. Run /clear (or start a fresh `claude` session / new terminal).

2. Paste the HANDOFF CONTEXT above as your first message.

3. Add: "Continue from the handoff context above. [your next task]"

```

## Common Mistakes

- Writing to a file without one of the File Mode triggers: an explicit request, a context-threshold nudge, or a `log-it` thin handoff.

- Putting an instruction for the receiving session only in this skill; the receiver reads the handoff, so anything it must do belongs in the handoff text.

- Committing a handoff file.

- Paraphrasing user requests or inventing constraints — both must be verbatim.

- Using `#` headers / bold / code fences in the content — breaks clean paste.

- Calling non-existent tools (`session_read`, `todoread`) — the conversation is already in context.

- Dropping the fixed re-read line from CONTEXT FOR CONTINUATION: without it the receiving side builds on stated status (tracker, review, store or console, inbox) that may have changed since the handoff was written.