handoff

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

Agent Strategy

Parallelize independent research. Launch in one message.

| What | Mode | Why | |---|---|---| | Step 1A (git/beads/ls) | Parallel Bash, never agents | Cheap commands; agent bootup wastes 15K+ each | | Step 1B context agents (OV, stale-refs, bible) | Parallel Bash inline; agents only if parent handoff >500 lines | Independent research | | Step 1C (conversation mining) | Main agent only | Only you have the history | | Steps 5+6 (beads/memory writes) | Parallel Bash | Independent writes |

Step 1: Deep Context Gathering

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

Run in one message as inline Bash calls:

| Commands | Returns | |---|---| | git log --oneline -20, git diff --stat, git status -s \| head -30, git branch --show-current | Branch, recent commits, uncommitted changes | | bd list --status=in_progress, bd list --status=open --priority=0,1, bd stats (skip if bd unavailable) | Active/open beads | | ls plans/handoffs/, ls .claude/handoffs/, ls plans/*.md | Existing handoff files |

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).

``bash 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:

| Task | Returns | |---|---| | OV Recall (if available): /memory-recall with 2-3 keyword searches | Prior decisions, failed approaches | | Parent Context (if parent exists): READ FULL PARENT — extract Goal, Where We Are, Key Decisions, What We Tried, Where We're Going, Open Questions, code identifiers | Parent summary for "Since Last Handoff" + identifier list | | Reference Docs: ls plans/BIBLE plans/bible BIBLE CLAUDE.md .claude/CLAUDE.md and read if found | Project context | | Stale Refs (if parent): Grep each parent identifier against current codebase | List of identifiers NOT found |

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 mining pass and announce it (this is not optional):

| Pass | When | Strategy | |---|---|---| | Quick | <100K context tokens | Single pass with extraction checklist below | | Deep | 100K-500K context tokens, OR 1M context + 20+ tool calls | Two passes — read references/mining-deep-chunked.md | | Chunked | 500K+ context tokens, OR 1M context + 50+ tool calls or >1hr work | Map-reduce — read references/mining-deep-chunked.md |

Write: "Mining with {Quick/Deep/Chunked} pass ({reason})." before starting. 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. Don't do map-reduce from memory.

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.

| | Standard (200K) | Extended (1M) | |---|---|---| | Target (aim for ceiling) | 300-400 lines | 500-800 lines | | Hard minimum | 150 lines | 250 lines | | Light session min | 80 lines | 120 lines | | Split threshold | 400 lines | 800 lines |

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 fir