Session Handoff

Calibration: Tier 1 (Model-compatible) - runs cleanly on the current dual-primary tier (Opus 5, Sonnet 5) as well as Haiku 4.5 with extended thinking. Structured retrieval, rule evaluation, or template lookup - output shape does not depend on model class. Correct-shape output also on Opus 4.8 (fallback-graceful) and Sonnet 4.6 (legacy-graceful). See repository README for model compatibility.

Version 2.0: Markdown output (was XML). Adds forced knowledge-file delta capture, a files-to-load-next-conversation list split by track, a chat echo of the starter prompt and load list, datetime-stamped naming with a Handoff Card, a completeness gate, and a carry-forward ledger that survives long handoff chains. v1.0 capture discipline preserved.

Produce a markdown session continuation document when multi-session work needs a clean breakpoint. The document is the next session's only inheritance from this one — it carries active tracks, decisions, knowledge gained, the files to reload, and open items so work resumes immediately instead of being re-derived.

Important

The handoff is everything the next session gets. The next session's Claude has no access to this conversation. Anything that matters lives in the handoff document or a persistent store (Memory, knowledge files, delivered files). Conversation-only content goes in the document at full fidelity, or it is lost.

These are gates. Each runs every handoff; skipping any produces a broken artifact:

• Knowledge-file deltas are never silent. Every handoff evaluates what the session learned that belongs in a knowledge file and emits drop-in KF blocks — or states KF deltas this session: none — confirmed. Absence is a deliberate, stated output, never an omission. This is the v2.0 headline: context gained in a session must reach the KFs, not evaporate.
• Decisions carry rationale. A decision logged as "chose X" forces the next session to follow blindly or re-derive. Capture the why and the implications. This is the #1 continuity failure.
• The completeness gate runs before emit. Verify every stream, decision, KF-delta evaluation, load list, carry-forward inheritance, and the starter prompt before finalizing. The gate is the backstop against silent drops.
• Output is markdown. Always. Structured markdown parses reliably and stays human-readable for direct review. Preserve the section schema and the status vocabulary; never substitute freeform structure.
• Each handoff is a snapshot, not a log. Continuing from a prior handoff replaces it. Unresolved items and pending KF deltas carry forward explicitly through the ledger. The document never grows by appending.

What the handoff must achieve

A correct handoff satisfies four outcomes. The method below is the reliable path to them, not a checklist to recite — lead with the outcome, let the steps serve it.

1. Complete capture. Every active work stream, decision, and piece of conversation-only knowledge is present at full fidelity.
2. Persistence-correct. Content that lives in a persistent store is referenced, not duplicated; content that exists only in this conversation is captured in full.
3. Forward-carrying. Pending KF deltas and unresolved open items from this session and any predecessor survive into the next handoff until applied or resolved.
4. Ingestion-optimized. Dense, specific, state-over-history, consistently structured, fast for the next session to act on.

How to get there

The method that reliably hits those outcomes:

Inventory the session. Catalog objectives, every activity track (starting state, progress, current state, next steps), decisions with rationale, uploaded content (working understanding, not raw text), conversation-only knowledge (most at-risk — exists nowhere else), artifacts, and open items. If continuing a chain, pull the predecessor's pending KF deltas and unresolved items.

Assess against the persistence test. For each item: if the next session's Claude wouldn't have it without this document, it goes in at full fidelity; otherwise it becomes a reference pointer. Memory edits → reference. Knowledge files → reference by name. Delivered files → reference path + {code}_ name. Conversation-only → full fidelity.

Evaluate KF deltas (gate). Separately from session progress, ask: what did this session learn or change that updates context for future sessions — methodology, principle, decision rationale, taxonomy, threshold, convention? Each qualifying item becomes a drop-in KF block (target file + section, action, the block, rationale), tagged with status and origin. If nothing qualifies, state it explicitly. Read references/handoff-template.md for the block format.

Structure to the schema. Organize into the markdown sections in references/handoff-template.md, leading with the Handoff Card. Apply ingestion optimization: density over prose, specific over summary, state over history (except rejected alternatives, which prevent re-proposal), consistent structure, re-upload flags on every ingested file.

Produce and verify. Output the handoff as a downloadable markdown file. Run the completeness gate. Produce the closeout checklist in conversation (read references/closeout-checklist.md). Echo the starter prompt and files-to-load list into the chat.

Naming and the Handoff Card

Filename: {code}_SH_{MMDDYY-HHMM}_{theme-slug}.md — e.g. root_SH_062426-1430_skill-calibration.md.

• {code} is the project code; if not yet established, ask once, then it is known.
• {MMDDYY-HHMM} is the datetime; chronological sort equals build order, so it is the unique sequence key — no integer is needed and none is written, which removes the duplication risk a manual counter would carry.
• {theme-slug} is 1–3 words, lowercase, hyphenated, capturing the session theme.
• Same-minute collision appends -2. A re-issued or corrected handoff for the same session appends _v2 to the stem; versioning disambiguates revisions, not order.

Handoff Card — the first block of the document body, ~5 lines, glanceable, ID matching the filename stem:

root · SH 062426-1430 · skill-calibration · v1
Reach-back: Self-contained
Carry-forward: 2 KF deltas pending, 1 open item carried
Advances: 4.8 alignment | session-handoff redesign

The reach-back line names the minimum predecessors needed to reconstruct this handoff (Self-contained, or Requires SH 062326-0900, …). When a stack of handoffs is loaded, chronological order of the datetime IDs is build order; orient by ID and reach-back rather than any written ordinal. Full card and reach-back rules: references/handoff-template.md.

The forward-carry mechanism

KF deltas and open items each carry a status (pending / applied / resolved) and an origin (the datetime ID of the handoff where they first appeared). When continuing a chain, inherit all still-pending KF deltas and unresolved open items from the predecessor(s), preserving origin — applied and resolved items drop out, so the ledger self-prunes. This is what makes "context never silently drops" hold across a 20-handoff chain, not just one hop. Flag any item carried across 2+ handoffs: stale (remove) or blocked (escalate).

Files to load next conversation

Distinct from project knowledge files (loaded into the Project, not the chat) and from per-source re-upload flags. List the conversation files needed to resume, split by track and by necessity — a "required to continue (all tracks)" group plus per-track groups marking each file required or optional. Derive from each track's next steps: which files do those steps depend on? Format: references/handoff-template.md.

Chat echo

After delivering the handoff file and the closeout checklist, post to the current chat, copy-paste-ready: the starter prompt (fenced) and the files-to-load list. Both also live in the handoff; the echo exists so the next conversation launches fast without opening the handoff first.

Proactive vs. requested

Requested ("wrap up," "create a handoff," "BSH"): full method at full depth. Finish in-flight deliverables that complete quickly first; thoroughness is the priority.

Proactive (context pressure ~70%): same outcomes and gates, urgency-aware execution. Inventory prioritizes in-flight over completed work; assess whether near-complete items (under ~10% of remaining budget) finish first; the document leads with active-track state and next steps, compresses completed work; the Card notes estimated remaining context. The KF-delta and completeness gates still run — pressure is not a reason to drop them.

Conventions

Recommended patterns, not platform requirements — adopt where they fit.

• Institutional memory file: if the project maintains a build_context.md or equivalent, the closeout assesses whether it needs updating and what. KF deltas captured in the handoff are often the source of that update.
• Propagation: if the session changed system-wide facts, flag propagation items so downstream references stay in sync. KF deltas are a first-class propagation vehicle.
• Phase-gated work: capture current phase, objectives, within-phase progress; cross-phase sessions document both.
• Cross-project artifacts: flag with the target project name in artifacts and as an explicit open item.
• Terse starter prompts: match the user's style; reference the handoff file, state the first action, done.
• Cloud storage as canonical: reference paths/URIs for files stored outside the conversation; note the delivery output path.

Examples

Example 1 — Single track, clean break, with a KF delta

A 2-hour Skill-design session. "Wrap this up."

Inventory: one track (Skill design), three decisions with rationale, no uploads, several conversation-only design-rationale items, one delivered spec file. Assess: spec file delivered → reference; decisions and rationale → full fidelity. KF-delta evaluation: the session established a reusable naming convention that future sessions must follow → one KF block (target: build_context.md › conventions, action ADD, the block, rationale), status pending, origin this handoff. Structure: Card, one track IN_PROGRESS, three decisions, one KF delta, one artifact, two open items, files-to-load (the spec, required), starter prompt. Produce + verify gate + echo.

Result: {code}_SH_062426-1610_skill-design.md. The naming convention reaches the KFs instead of living only in the dead conversation.

Example 2 — Continuing a chain, carry-forward in action

Session 3 in a chain. The prior handoff left 2 pending KF deltas and 1 unresolved open item; this session applied 1 delta and resolved nothing.

Inventory pulls the predecessor's ledger. Carry-forward: the 1 still-pending KF delta re-surfaces with its original origin ID; the applied delta drops; the unresolved open item carries with its origin; this session adds 1 new delta. The item now carried across 3 handoffs is flagged — escalate or remove. Reach-back: this handoff integrated the predecessor's still-relevant decisions, so Self-contained; had it left a large ingested-content summary in the predecessor, it would name it.

Result: nothing from three sessions back falls through; the ledger shows exactly what is still pending and where each item originated.

Example 3 — Proactive trigger

Context pressure ~70%. Two tracks, one ~80% done, one ~30%. The ~80% track needs ~5% of remaining budget — finish it first, then run the method. Document leads with the 30% track at full detail, compresses the completed one. KF-delta and completeness gates still run. Starter prompt focuses on the 30% track; Card notes remaining context.

When to Use This Skill

Use when approaching context limits and continuing in a new session, wrapping up a session with intent to continue, managing multi-track work across conversation boundaries, or when context pressure hits ~70% and in-flight work cannot complete.

Do NOT use for optimizing Memory content (use rootnode-memory-optimization if available), analyzing context budget (use rootnode-context-budget if available), auditing project structure (use rootnode-project-audit if available), deciding whether work is ready for autonomous/Claude Code execution (use rootnode-handoff-trigger-check if available), summarizing with no continuation intent, or when work is fully complete with no pending items.

Troubleshooting

Next session doesn't resume cleanly: starter prompt too vague, or conversation-only knowledge was summarized instead of captured at full fidelity. The prompt must name the handoff file, state the first action, and orient to the project.

Decisions get re-litigated: rationale missing or thin. Capture the reasoning, the implications, and any rejected alternative so it isn't re-proposed.

Context gained in a session never reaches the KFs: the KF-delta gate was skipped or produced an empty result without the explicit confirmation line. Every handoff emits blocks or none — confirmed. If deltas exist, they belong in the handoff body with status and origin, not only flagged in the closeout.

Items fall through across sessions: carry-forward inheritance didn't run. When continuing a chain, inherit all pending KF deltas and unresolved items with origin preserved. Check the ledger.

Handoff numbering or order is ambiguous: rely on the datetime ID, not a written count — chronological order of {MMDDYY-HHMM} is build order. Use _v2 only for a re-issue of the same handoff.

Uploaded file content lost between sessions: re-upload flag wrong, or the key-content summary too thin. Capture every fact, constraint, or data point that influenced the work.

Handoff too long for the next context: too much completed-work detail. Compress completed tracks to final state; the next session needs current state and next steps.

Reference table

Reference	When to read
references/handoff-template.md	The markdown schema — all section formats, status vocabulary, Handoff Card, KF-delta block, files-to-load, carry-forward ledger, reach-back, naming. Read when structuring and producing.
references/closeout-checklist.md	The closeout checklist delivered in chat — Memory update patterns, build_context assessment, propagation (KF deltas as vehicle), chain handling, cross-project items, chat echo, completeness line. Read at produce.

End of SKILL.md.