Session Handoff

Guards:

• Not plan mode. This skill writes files. If in Claude Code plan mode, exit first.
• Not shadowing. NEVER generate handoff-like documents freeform. Freeform summaries look right but lack chain tracking, self-validation, and evidence mining. Only this skill produces handoffs.
• Not when discussing. Only run when the user explicitly asks to CREATE a handoff right now. If ambiguous ("what does handoff do", "edit the handoff file"), ask first.

Typical use: ~75% context. You have a lot of conversation to mine — extract maximum value before closing. On 1M context that's ~750K tokens of history.

The user should not need to provide anything — /handoff alone is sufficient.

Arguments: $ARGUMENTS

Compact mode

If $ARGUMENTS contains the word compact-mode, the compact-handoff mod started this run. It replaces the conversation with this handoff when your turn ends, so the turn must finish with nothing pending:

• Run Steps 1-6 exactly as normal. context={N}k in $ARGUMENTS is the session's size as Claude Code measured it: choose the mining pass from it. Anything else in $ARGUMENTS is the framing hint. Compact mode shortens only the ending: the mining pass, its reference, the line minimum, Phase 2 and the Length check apply in full, and matter more, because the conversation is deleted after this turn. The mod counts the lines itself and won't compact a handoff under its pass minimum.
• Step 7: one line only (file path, the Length check line, chain seq). The compaction replaces this turn seconds later, so a full report is wasted output.
• Ask nothing in this turn. Where a step says to ask (e.g. Tier B "Any doubt"), take its stated default and note the choice in the handoff.
• Step 8: don't ask. Follow the Yes flow in references/close-session.md (append ## Session Closed, commit, print the paste prompt), skipping its step 4.
• Print the paste prompt block exactly as the template has it: the PASTE THIS INTO YOUR NEXT SESSION: header, the dashed rules, the (seq {N}, {chain_tag}) line and the onboarding steps. The mod sends that block as the next prompt word for word. Never shorten it to one line, even when you reused or restored an existing handoff instead of writing a new one.
• End your turn with this exact last line, path relative to the repo root:

COMPACT-HANDOFF-READY: {handoff path}

• If no handoff file could be written, end with COMPACT-HANDOFF-FAILED: {reason} instead. The mod then leaves the context untouched.

Agent Strategy

Parallelize independent research. Launch in one message.

Step 1: Deep Context Gathering

1A: External State (parallel Bash — never agents)

Run in one message as inline Bash calls:

1B: Chain Detection

Resolve the chain tag (use first that applies):

1. Epic exists → use epic name/ID
2. 1-4 beads → use all bead IDs (e.g., myproject-xxxx, myproject-yyyy)
3. 5+ beads → pick 2-3 most relevant to the primary work stream
4. No beads/epic → generate fallback: python -c "import secrets; print(secrets.token_hex(4))" → standalone-{hex}

Find prior handoff in this chain (two tiers, stop at first match):

• Tier A — Paste Prompt (deterministic). Did the user start this session by pasting something like Read HANDOFF_foo_date.md (seq 2, chain-x) and continue...? If yes, that file is the parent. Read its header. Continuation — seq = parent's + 1.

• Tier B — Bead/Epic Scan (heuristic, skips auto-handoffs).

  grep -l "Chain:.*{chain_tag}" plans/handoffs/HANDOFF_*.md 2>/dev/null \
    | xargs grep -L "^\*\*Auto:\*\* true" 2>/dev/null

A shared bead is a CANDIDATE, not proof of continuation. Before claiming the match as parent:

1. Read the candidate's ## Where We're Going section.
2. Is current session work a direct follow-on of those steps? (Same feature/fix, continuing the named next-actions?)
3. Clear continuation → inherit chain, increment seq, set parent.
4. Unclear or unrelated → treat this as seq 1 (new chain). Add a ## Related Handoffs section listing the sibling file as reference only, NOT parent. A bead can host many independent work streams (brainstorm → impl → testing) — don't conflate them.
5. Any doubt → ask the user: "Found prior handoff {file} on same bead. Is this session a continuation? (default: new chain)"

Neither tier matches: seq 1, parent: none.

1B-3/4: Context Agents (parallel, inline Bash unless parent is huge)

Once chain tag resolved, launch in parallel:

Parent reading is MANDATORY when a parent exists. "Since Last Handoff" requires comparing what was planned vs what happened. Skip agents that don't apply.

1C: Conversation Mining

If arguments were provided ($ARGUMENTS), use as a soft hint for framing. Conversation is ground truth.

Choose the mining pass and announce it (this is not optional). Go by the context size: if $ARGUMENTS has context={N}k, use that number, not your own estimate. Otherwise use the size you can see; if you can't tell, choose the larger pass.

Print one line before starting: Mining pass: {Quick/Deep/Chunked} ({size}, {reason}), e.g. Mining pass: Chunked (677k tokens, 100+ tool calls). Don't use numeric names — they collide with chain seq numbers.

For Deep or Chunked, read references/mining-deep-chunked.md NOW for the multi-pass protocol: an actual Read call, before any Write. Don't do map-reduce from memory. Announcing the pass and skipping its reference is how a 757K-token session came out at 346 lines.

Extraction checklist (apply per pass):

• [ ] Goals & objectives (user's target, overarching epic)
• [ ] Work completed (every file modified, function changed, with specifics)
• [ ] Approaches tried (chronological, successful and failed)
• [ ] Failed approaches + why (MOST expensive to re-discover)
• [ ] Test results & measurements (raw numbers)
• [ ] Data files created (paths to JSON/CSV/logs)
• [ ] Decisions made + rejected alternatives
• [ ] Discoveries & gotchas
• [ ] Code analysis (signatures, thresholds, constants)
• [ ] User preferences expressed
• [ ] Remaining questions
• [ ] Dependencies on other work

If you're skimming, STOP. Re-read. Details are the value.

Step 2: Choose Output Location

First directory that exists (or create plans/handoffs/):

1. plans/handoffs/
2. .claude/handoffs/

Step 3: Generate File Name

• With beads: HANDOFF_{chain_tag}_{slug}_{YYYY-MM-DD}.md (e.g., HANDOFF_myproject-xxxx_auth-rewrite_2026-03-19.md). For multi-bead, use primary bead only.
• No beads: HANDOFF_{slug}_{YYYY-MM-DD}.md
• Slug: 2-4 word kebab-case.
• Collision: append _2, _3, etc.

Step 4: Write the Handoff File

Read `references/output-template.md` for the full file structure. It defines every section (Goal, Where We Are, What We Tried, Evidence & Data, etc.) with composition rules.

Line Budget

Check your system prompt for context window size.

Target the CEILING. An 800-line handoff on 1M context is ~0.7% of the window — negligible cost, huge savings. Too-long is cheap; too-short costs hours of re-investigation.

Two-Phase Write

1. Phase 1 — Initial Write. Compose and write everything in ONE Write call. All sections.

Phase 1 MUST hit the pass minimum on its own — Quick: 150+ standard / 250+ extended, Deep: 300+, Chunked: 500+. Phase 1 is not a rough draft; it's the baseline. If you find yourself planning to "flesh it out in Phase 2," stop and expand the current sections before writing.

1. Phase 2 — Gap Research. After writing, count lines. Read your file back. Scan conversation for data you didn't capture (tables skipped, mid-session feedback missed, measurements without numbers, approaches mentioned but not detailed). Use Edit to append toward the ceiling.

Phase 2 is for gaps, not for baseline. If Phase 2 needs to add 50+ lines to reach the minimum, Phase 1 was under-mined.

Phase 2 is MANDATORY for Deep and Chunked passes. Optional for Quick — but run it if your first pass is below the ceiling by >20%.

Splitting: only if final file exceeds threshold. Under threshold = one file.

Step 4-CHECK: Self-Validation

First, the Length check. Count with a tool call, not an estimate (wc -l {handoff path}), and print one line:

Length check: {n} of {min} lines ({pass} pass) ✓ when it meets the minimum, or Length check: {n} of {min} lines ({pass} pass) ✗ not finished when it doesn't.

Minimums: Quick 150 standard / 250 extended, Deep 300, Chunked 500.

✗ means the handoff is not finished. Go back through the conversation, early, middle and late, and extract what the file is missing: decisions, numbers, failed approaches, file paths, user feedback. Don't pad: appendices that restate the file, or lists rebuilt from what it already says, don't count. Count again. Never call the handoff validated, and never go on to Step 5, while the Length check shows ✗.

Then read `references/validation.md` and run every other check. If any fails, expand thin sections before proceeding.

Steps 5 + 6: Update Beads & Persist Memory (parallel Bash)

# Beads (if in_progress work exists)
bd update {id} --notes "Handoff written. See {file_path}"

# Memory (if bd remember available)
bd remember "Handoff: {path}. Chain: {chain_tag} seq {N}. Status: {status}. Next: {next action}"

Step 7: Report

Tell the user concisely:

• File path(s) and the final Length check line, verbatim
• Chain info (tag, seq, new vs continuation)
• Self-check outcome (and what was expanded if first pass failed)
• The Next Action

Step 8: Ask to Close Session

Ask:

Handoff complete. Ready to close this session?

>

- Yes — I'll commit, mark "session closed", give you a paste prompt for the next session. - No — We keep working. Say "close session" when done.

>

(Defaults to commit — say "close without commit" to skip.)

Based on the answer, read `references/close-session.md` and follow the flow for Yes / No / "close without commit".

Cleanup: Archiving Completed Chains

When bead/epic is closed and all work is done:

# Find all handoffs for a bead or epic
grep -l 'Chain:.*{bead_id_or_epic}' plans/handoffs/HANDOFF_*.md plans/handoffs/PLAN_*.md 2>/dev/null

# Archive (don't delete — old decisions are useful)
mkdir -p plans/handoffs/archive/
mv {files} plans/handoffs/archive/