# Session Handoff

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

- Skill: `cleanexpo/session-handoff` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cleanexpo/session-handoff`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cleanexpo/session-handoff/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: cleanexpo (https://skillmd.com/u/cleanexpo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cleanexpo/session-handoff

---


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

```bash
scripts/handoff-loop.sh          # --quick for interim; --full to install deps first
```

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

1. Every task/goal the session set out to do is done, or explicitly deferred in §7 with an owner.
2. Tests actually ran green (Phase 0 exit 0) — not just types compiling; cite the log path.
3. `git status` clean and `git stash list` empty — nothing uncommitted belongs in the change.
4. Work is PR'd (SHIPPED) or carries the exact ready-to-open command (READY-TO-SHIP).
5. 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

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

1. 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
2. Where it started (request, branch, files, problem, constraints; `Unknown from available context` if unclear)
3. Decisions locked + what shipped (separate decisions from implementation; if nothing committed/pushed, say `Nothing shipped yet. Current work is local/session-only.`)
4. Key files (table; Status ∈ Created / Modified / Deleted / Read-only inspected / Needs review / Deferred / Unknown)
5. Running state (never claim a process is running unless verified)
6. Verification — exact commands (backend / dashboard / smoke / skill check)
7. Deferred + open questions (two separate lists, each with Owner / Blocking / Why)
8. Pick up here (`Start here` steps, `Do not redo`, and an explicit `First command to run`)
9. Risk notes (unverified assumptions, failed commands, stale context, secrets/env gaps)
10. 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]]