Handoff

Handoff - Self-Contained Next-Session Prompt

Overview

Produce one prompt that a fresh Claude - with zero memory of this conversation - can act on immediately. The defining constraint: the next session starts with 0 context. Everything it needs to continue must live inside the prompt text. No "as we discussed", no nickname left undefined, no bare file path the reader can't place.

Standalone by design: no runbook, no audit trail, no persisted repo file. Just the prompt.

When to use

• Wrapping up; you'll continue this work in a new chat (clearing context, hitting the context limit, switching machines).
• You want a copy-pasteable brief that stands entirely on its own.

Not when you're partway through a procedure that already keeps its own audit trail on disk. A handoff that ignores that trail duplicates it and the two drift. If your setup has a handoff skill that links the procedure and its audit files, use that one - claude-ssh-partner ships runbook-handoff for exactly this case.

What you produce

One artifact, two channels carrying identical bytes:

1. Stdout - in a fenced ```markdown block.
2. macOS clipboard - via pbcopy.

No repo file. No commit.

Procedure

1. Gather state (read-only)

Pull what the next session needs from this one:

• git status + git diff --stat and git log -8 --oneline - committed vs uncommitted work.
• TaskList - any in-progress / pending items.
• The conversation's goal, the key files touched, and any decisions or dead-ends reached.

2. Assemble the prompt (the contract)

The prompt MUST contain these sections, in this order. Fill every angle bracket; omit a section only where it's marked optional.

# <Topic - one line, e.g. "Finish the retry backoff in the billing worker">

## Goal
<One sentence: what we're trying to achieve.>

## Background
<2-5 sentences a stranger needs. Define every entity the first time it appears -
repo, server, ticket ID, service name. A name with no definition fails the test below.>

## State
<What's done so far. Committed? cite the sha + message. Uncommitted? where, and what.
Current status in one or two lines.>

## Next
<The concrete next action(s), specific and ordered. Not "continue the work" - say
exactly what to do first.>

## Files & commands
- `<absolute/path>` - <one line: what it is / why it matters>
- `<command>` - <what it does>

## Gotchas  (optional - omit if none)
<Constraints, things already tried that didn't work, things NOT to do.>

Keep it scannable - roughly one screen. No prose summaries of the conversation.

3. Self-containment test (before printing)

Re-read the assembled prompt as if you had never seen this conversation. Every name, path, ID, and pronoun ("it", "that", "the issue") must resolve from the prompt text alone. If anything leans on shared memory, rewrite it to name the thing explicitly. This test is the whole point of the skill - do not skip it.

4. Deliver

Write the finished prompt to a scratch file and copy it (one Bash call - the quoted heredoc delimiter keeps $, backticks, etc. literal):

cat > /tmp/claude-handoff.md <<'HANDOFF_EOF'
<the exact assembled prompt, verbatim>
HANDOFF_EOF
pbcopy < /tmp/claude-handoff.md

Print the same text in a fenced ```markdown block in the chat, then close with one status line:

✓ self-contained handoff copied to clipboard - paste into a fresh conversation

Critical rules

• Zero-context readable. A reader with no memory of this session can act on it. Define every entity; expand every "it".
• Same bytes everywhere. The printed block and the clipboard match exactly.
• Absolute paths with a one-line gloss - the next session can't infer your cwd or what a file is for.
• No prose around the printed block. The user is copy-pasting.
• No file in the repo, no commit. The prompt is ephemeral; its home is the next conversation.
• No follow-up suggestions. The handoff prompt itself contains the next action.