| name | session-handoff |
| description | Durable session handoff (/session-handoff). Gates the tree green via scripts/handoff-loop.sh, classifies the session SHIPPED / READY-TO-SHIP / WIP-BLOCKED against a Definition-of-Done, then generates a precise handoff before stopping, switching terminals, opening a PR, handing work to another agent, or resuming later. Refuses to present unfinished work as a clean stop; for ready work hands off the exact merge-gate-guarded ship command. Writes a durable report + healthcheck log; the "1" of the 1-2 combo with /resume-from-handoff. Captures what was done, decisions locked, what shipped, key files, running state, verification, deferred/open questions, exact pickup point, risk notes, and a quality check. |
| owner_role | Tier-Architect (end-of-session handoff; gate-then-report) |
| status | active |
| automation | manual |
session-handoff — Durable Session Handoff
The "1" of the handoff combo with /resume-from-handoff: gate the tree green, then write
a durable handoff the resume side verifies against. It runs LOCAL verification gates and
writes the report + log — but never commits, pushes, deploys, migrates, modifies tickets,
rotates secrets, or touches production. Any such mutation follows a separate, explicit user
request after the handoff.
Companion to judge: /judge decides whether to build; /session-handoff records
what happened and where the next agent picks up. Distinct from tao-judge (machine
loop-termination scorer).
Phase 0 — Gate the tree green (run first, every time)
scripts/handoff-loop.sh
Runs the definition-of-done gates (clean → deps → generated-files → type → lint → tests →
build → audits), logging to .handoff-logs/handoff-<ts>.log. Exit 0 → write the handoff.
Non-zero → write a BLOCKED handoff naming the failing gate; do not claim ready.
Phase 0.5 — Definition of Done & ship classification (before writing the report)
Phase 0 proves the tree green; Phase 0.5 proves the session finished — a green tree can hide
half-done, uncommitted, or never-shipped work. Never let an unfinished session pass as a clean
stop. Classify into exactly one state and record it in §1:
- SHIPPED — committed, pushed, PR open/merged on a green tip. Record the PR URL in §3.
- READY-TO-SHIP — complete + green but no PR yet. Do not silently stop: run the
merge-gate
pre-open checklist, then make §8's First command the exact gh pr create. session-handoff
does not open it — opening a PR here ≈ merging it (see merge-gate).
- WIP / BLOCKED — a task unfinished, a gate red, or a surface not demonstrable. Mark the
handoff INCOMPLETE; §7 lists what remains to finish + test, §8 is the finish-then-ship path.
Definition-of-Done (answer each from a this-session tool result; any "no" forbids SHIPPED):
- Every task/goal the session set out to do is done, or explicitly deferred in §7 with an owner.
- Tests actually ran green (Phase 0 exit 0) — not just types compiling; cite the log path.
git status clean and git stash list empty — nothing uncommitted belongs in the change.- Work is PR'd (SHIPPED) or carries the exact ready-to-open command (READY-TO-SHIP).
- Any user-visible change has a demonstrable outcome (RA-1109), not just HTTP 200 / green CI.
For READY-TO-SHIP, the handed-off gh pr create is only safe when all merge-gate Iron-Law
conditions already hold (Whole · Green-on-pushed-tip · Dark-by-default · Atomic · Standards-clean
· Authority reconciled). Any false ⇒ the session is WIP, not READY-TO-SHIP. Invoke merge-gate
for the full gate; do not paraphrase it.
Input scope
Handoff scope is supplied as $ARGUMENTS (a ticket, branch, PR, feature, or repo area).
If empty, infer scope from the current branch, git status, recent commits, current diff,
recently changed files, conversation context, and the CLAUDE.md / AGENTS.md guidance.
Inspection
git branch --show-current
git status --short
git log --oneline -n 8
git diff --stat
git diff --name-only
Required output — Session Handoff
Write it to docs/session-handoffs/handoff-<ts>.md (so /resume-from-handoff can find
it) AND print it. Use this structure (see .session-handoff/report-template.md); cite the
Phase 0 log path in §5/§6:
- Summary of what was done (attempted / completed / partial / not touched) + the Phase 0.5 state (SHIPPED / READY-TO-SHIP / WIP-BLOCKED) and one-line Definition-of-Done result
- Where it started (request, branch, files, problem, constraints;
Unknown from available context if unclear)
- Decisions locked + what shipped (separate decisions from implementation; if nothing committed/pushed, say
Nothing shipped yet. Current work is local/session-only.)
- Key files (table; Status ∈ Created / Modified / Deleted / Read-only inspected / Needs review / Deferred / Unknown)
- Running state (never claim a process is running unless verified)
- Verification — exact commands (backend / dashboard / smoke / skill check)
- Deferred + open questions (two separate lists, each with Owner / Blocking / Why)
- Pick up here (
Start here steps, Do not redo, and an explicit First command to run)
- Risk notes (unverified assumptions, failed commands, stale context, secrets/env gaps)
- Handoff quality check
End with: Handoff complete. Next safe action: <one sentence>.
Quality rules
- Do not claim tests passed unless they were actually run.
- Do not claim anything shipped unless commit/push/merge evidence exists.
- Do not claim a process is running unless verified.
- Clearly separate completed work from deferred work.
- Always provide the first command the next agent should run.
The 1-2 combo
/session-handoff (this) gates + writes; /resume-from-handoff reads the latest
docs/session-handoffs/ report and re-runs scripts/handoff-loop.sh before resuming — the
tree is proven green on the way out AND back in.
Companion: merge-gate (the ship boundary)
Phase 0.5 decides whether a session is ready to ship; merge-gate owns how it ships safely.
session-handoff never opens a PR itself — for READY-TO-SHIP it hands off the exact gh pr create
in §8, gated by merge-gate's Iron Law (opening a PR in this estate ≈ authorising its merge).
Division of labour: session-handoff = the definition-of-done gate run + completion
classification; merge-gate = the git-merge boundary and auto-merge threat; ship-chain /
ship-it / ship-release = the idea→ship lifecycle. Invoke merge-gate before any handed-off
ship command.
Fork-slice mode (Pocock /handoff, 2026-07)
Lightweight alternative to the full Definition-of-Done gate for mid-task context forks:
spinning an out-of-scope task (bug, refactor, prototype spike) into a fresh agent while the
current session keeps working. No Phase 0 gate, no classification, no durable report — instead
of /compact (loses fork ability) or /clear (loses everything), the fresh agent boots from
a slice:
- Write a context-slice markdown to a temp path (e.g.
$TMPDIR/handoff-<slug>.md), never
the workspace — disposable by design. Contents: task state, decisions made, next action, and
a suggested-skills list the fresh session should invoke.
- State the fork's purpose explicitly — a slice can't be written without knowing its consumer.
- Pointers, not duplication: reference existing docs/issues rather than restating them. Redact
secrets/PII (the file lands in a temp dir).
- Boomerang: a spike session can write a slice back to the parent capturing non-obvious learnings.
Which mode: mid-task fork / parallel spike / prototype-and-return → fork-slice. Stopping,
switching terminals, opening a PR, or handing work to another agent → the full Phase 0 + DoD
gate above. Fork-slice never replaces the terminal gate.
Provenance: [[pocock-handoff-skill-2026-07-14-ingest]]
