Handoff

The conversation has gotten long enough that it needs to end. Write the message that lets the next session pick the work up cold.

Write it the way you'd hand a task to a colleague taking over because you got pulled onto something else. They're competent and they have the repo — they don't need a tour, they need to know where things stand and what would bite them.

The Process

0. Read the note

$ARGUMENTS is an optional note from Josh. When it's empty, skip to step 1. When present, treat it as steering for the whole draft.

A note typically does one of these:

The note outranks the filter in step 2 — if Josh says to include something, include it even if it's re-derivable. It never loosens the cap in step 3 unless he says so.

1. Mine the conversation, not the repo

Everything in the handoff comes from this conversation. The next session can read code, run git log, and load CLAUDE.md on its own.

Look for:

2. Apply the filter

For each candidate, ask: can the next session get this by looking?

• Yes → cut it. File contents, function names, line numbers, what a diff already shows, anything in CLAUDE.md or the rules.
• No → keep it. It only exists in this conversation.

The filter applies to facts, not to orientation. One or two plain sentences establishing what the work is and where it's happening are worth their space — the next session shouldn't have to reverse-engineer the task from a branch name. Orient in prose; don't inventory.

3. Write it

Address the next session directly. Prose and short bullets, no section headers, no nested structure. Name a file only when the location itself is the point.

Hard cap: 30 lines or 400 words. If it doesn't fit, the filter wasn't applied hard enough — cut re-derivable content, not the decisions.

Example shape:

Picking up mid-work on the session-refresh fix in ~/work/api, branch fix/token-refresh.

The refresh runs before the redirect now and there's a test covering the expired-token path. What's left: the mobile client hits the same code path and hasn't been checked.

Things worth knowing:

• Josh rejected wrapping this in a middleware layer twice — he wants it inline.
• The retry helper looked like the right place for this and isn't; it swallows the 401.
• Integration tests need TEST_DB_URL exported or they fail with a confusing DNS error.

4. Present and refine

Go straight into the draft. Don't wait for confirmation.

Print the draft as rendered markdown in the response body — not fenced, not indented, no wrapper. Backticks, bold, and bullets should display as formatting so Josh reads it the way it will land. Stop there — no commentary, no explanation of choices.

Josh will refine. Rewrite the whole draft each time and reprint it; don't describe edits.

5. Copy on approval

When Josh approves ("good to go", "ship it", "copy it"), pipe the markdown source of the approved draft — the version with the backticks and asterisks intact — to pbcopy:

cat <<'EOF' | pbcopy
<final handoff text>
EOF

The quoted 'EOF' matters — it stops the shell expanding backticks and $ in the text.

Confirm in one line: "Copied."

Rules

• Conversation only. If it came from a file, it doesn't go in.
• No stale context. Write the current state. A rejected approach appears only as a warning not to retry it, never as history.
• No meta. Don't describe the handoff, count what you included, or note what you left out.
• Prose over structure. Headers and nested bullets turn it back into the document this is meant to replace.