--- name: session-handoff description: "Close a working session with a balance sheet, not a diary — one copyable block carrying the closing position, only the deltas, and exactly one next move. Every SHIPPED line carries a commit hash AND a re-runnable check, verified against ground truth rather than the session narrative. Reach for it on wrap up, close the session, or whenever a cold session will have to resume from this one." --- # Session Handoffs ## The one idea **A handoff is a balance sheet, not a diary.** A cold session — new context, no memory of this one — pastes the handoff in and has to resume at full speed without re-deriving anything. So the handoff carries three things and almost nothing else: the true closing position, the deltas since the last close, and exactly one next move. And every line in the SHIPPED section carries its proof. This is the part that matters most, because the most expensive handoff failure is not an omission — it is an *overstatement*. A handoff that reports a commit which isn't on disk sends the next session building on a floor that was never poured. A missing detail costs a question; a false "shipped" costs a session built on sand. > An unverifiable "shipped" line is an unsupported journal entry — and the next session > will book against it. That is why the handoff lands *before* any new work begins (it is the shift-change record, not an afterthought), why it is one copyable block (it gets transplanted whole), and why it is ruthless about deltas (a restatement of unchanged state is just noise the next session has to read past). ## When to reach for this - The user says "initiate handoff," "wrap up," "close the session," or anything that signals the session is ending. - A future cold session will need to resume from this one — i.e. nearly every session. - You're tempted to write a loose narrative of what happened. That's the diary; this skill is the balance-sheet replacement. - Proactively recommend initiating a handoff when context is hot and valuable but the token cost of continuing is climbing — name that tradeoff explicitly, and include a recommended effort level for the handoff itself. ## The anatomy — each section and the reason it's there 1. **One fenced block, verbatim-copyable.** The handoff is pasted whole into a cold session to orient it. Rendered prose with live formatting gets mangled on paste and forces a re-read; one fenced block is a clean transplant. 2. **A masthead + `YOU ARE HERE` (three trails).** The cold session's first question is "where am I on the map?" The three trails — the core arc, the product slice, and a one-line infrastructure state — locate the work on all three axes in one line, so the next session never re-derives project state from the repo. 3. **`SESSION ARC` — one line.** "Came to do X → found Y → pivoted to Z." The shape of the session in a single sentence. It tells the next session whether this was a clean build or a pivot, which sets the reading posture for everything below. 4. **`🔧 STACK DELTA` — only what changed.** Not the full stack; the diff. The next session already knows the stack from prior handoffs — it needs the change. Delta discipline is what keeps the handoff from bloating into a restatement of everything. 5. **`✅ SHIPPED` — a commit hash and a re-runnable check on every line.** The load-bearing section, and the one that fails. Each line is a booked transaction and must carry its proof: a hash you could inspect, AND a specific observation you could re-run and watch pass ("fire-tested 4/4," "flag fires on the seeded profile, silent on the control"). If a line can't carry both, it is not shipped — it is IN PROGRESS, or it becomes the START HERE. 6. **`🔴 START HERE` — exactly one opener, with an effort level.** One thing the next session does first, pre-scoped enough to act on without a discovery tax, tagged STANDARD / HIGH / MAX with a one-line rationale. One opener, not a menu — so the next session's first move is work, not a decision about what to work on. 7. **`📋 BACKLOG DELTA` — transactions, not the ledger.** The backlog is the system of record; the handoff carries only the rows added or changed this session. A pointer at the ledger, never a copy of it — a duplicated backlog is a second ledger that drifts. 8. **`💡 BANKED` — the lesson, not the log.** The transferable principle this session earned, so it survives even if the code doesn't. Conditional sections — **include only when the session was investigative or pivoted:** - **`🔬 EVIDENCE LOCKER`** — the numbers, snapshot, or artifact paths backing a finding, so the claim can be re-checked rather than re-trusted. - **`🚫 RULED OUT / DON'T REDO`** — the dead ends, so the next session doesn't re-walk them. (High value — this is the section that prevents repeated investigation.) - **`⚖️ OPEN DECISION`** — an unresolved fork, framed as options + your recommendation, so the next session ratifies rather than re-derives. ## The rule that makes it trustworthy (worth its own callout) The SHIPPED section is a ledger of booked transactions, and every line carries two things: a commit hash, and a verification someone else could run. "Done," "works," "refactored the pipeline" are not verifications — they are vibes. "Fire-tested 4/4," "the log shows `` at the tip," "the gate fires on the seeded profile and stays silent on the control" are verifications, because they are *checkable by someone who wasn't here*. And the check is run against **ground truth** — the commit log, the disk, the service manager — never against the session's own narrative. The narrative is exactly where overstatement lives: a session can vividly describe a commit it discussed and never actually made. The proof rule exists to make the handoff immune to its own storytelling. ## The deeper principle (the transfer) A handoff is a period-close. `YOU ARE HERE` is the closing position; `✅ SHIPPED` is the period's journal entries, each with supporting documentation; `⚖️ OPEN DECISION` is the open items; `🔴 START HERE` is the next-period opener. The discipline that makes a close auditable — every entry tied to a verifiable transaction — is the same discipline that makes a handoff safe to resume from. The enterprise version swaps the mastheads and keeps the law: an agent reporting to the next shift, or to a human reviewer, states its *verifiable position and the proof* — never a narrative of effort. "I worked on the reconciliation" is a diary line. "The rec is tied out; here is the supporting schedule" is a balance-sheet line. Position-plus-proof is the whole governance story in a single artifact. ## The closing recap (spoken, just before the block) Every initiate-handoff opens with a short spoken recap delivered *immediately before* the fenced block — auto-delivered, no proceed gate. ~15 seconds, ~40 words max: one sentence naming the session's single biggest move and the next opener ("killed X by doing Y → fire-tested → committed clean; next session builds Z"). It is the out-loud `YOU ARE HERE` — the listener re-orients in one breath before the block scrolls past. **Not voice-session-only: it rides every handoff.** Follow it with a one-line "initiating the handoff," then the block. ## Pre-flight checklist (run before emitting the block) - Every `✅ SHIPPED` line has a real commit hash AND a check you could re-run? If you can't name the check, it isn't shipped. - Verified against the commit log / disk / the service manager — not against the session narrative? - Is every line a DELTA? Cut anything that restates unchanged state. - Exactly one `🔴 START HERE`, carrying a recommended effort level? - `📋 BACKLOG DELTA` points at the ledger — it does not duplicate it? - One fenced block, copyable verbatim — not rendered prose? - Spoken ~15s / ~40-word recap delivered immediately before the block — auto, no proceed gate, every handoff (not voice-only)? - Conditional sections present *only* if the session was investigative or pivoted? (No ceremony carrying no failure to offset.) ## Template (skeleton) *Deliver the spoken recap (above) first, then emit this block.* ``` 🌲 SESSION HANDOFF — YOU ARE HERE Arc: Product: Infra: SESSION ARC Came to → found → . 🔧 STACK DELTA ✅ SHIPPED (every line: commit hash + a verification you could re-run) • — — • — — (No hash + re-runnable check → NOT shipped. Mark IN PROGRESS or move to START HERE.) 🔴 START HERE (exactly one opener, pre-scoped, with an effort level) — effort: , . 📋 BACKLOG DELTA (transactions against the ledger — pointer, not a copy) • + | (added) • → done | rescoped (changed) 💡 BANKED • ─── conditional: investigative / pivoted sessions only ─── 🔬 EVIDENCE LOCKER 🚫 RULED OUT / DON'T REDO ⚖️ OPEN DECISION ``` ## Anti-patterns — the handoff that fails the next session - **SHIPPED with no hash or no check** ("refactored the pipeline") → an unsupported entry; the next session books against a phantom floor. - **Verifying against the session's own narrative** instead of the log or the disk → exactly how a commit that was discussed-but-never-made gets reported as shipped. - **Restating the full stack** instead of the delta → the next session re-reads what it already knew. - **A START HERE menu** instead of one entry → the next session's first move becomes a decision rather than work. - **Copying the backlog into the handoff** → a second ledger that drifts from the real one. - **Rendered prose instead of one code block** → mangled on paste, forces a re-read. - **Skipping the spoken recap** → the listener has to read the whole block to find the one thing that changed; the recap is the out-loud `YOU ARE HERE`. - **Conditional sections on a clean linear build** → ceremony carrying no failure mode, which violates the expiry principle (every ceremony should offset a real risk). ## Provenance Distilled from a locked handoff format. The SHIPPED-proof rule is the direct response to a session where a backlog row was narrated as committed but was never on disk, and the anchored-edit method was abandoned mid-flight — a handoff written from the narrative would have carried that overstatement forward into the next session. The handoff's one job is to make that class of error impossible: position plus proof, checked against ground truth, every time. The spoken recap was added later — confirmed a must-have after it let a listener re-orient in one breath before the block scrolled.