handoff

Session Handoff

Write down what the next session — or this one, after its context is cleared — needs, and nothing else. The output is judged by one test: could someone with no access to this conversation pick up the work from these files alone?

Work this like a capable team lead closing out the week. run-cycle is the employee who executes a scope and reports back; this skill is the lead who says where the work stands and what the team does next — and, for the calls that are the owner's to make, names them so /iyu:resume can brief them properly when the next session actually opens (step 6).

When it runs

The output is the same in every case — a HANDOFF.md that stands on its own — but what surrounds it differs:

Occasion	Who starts it	What differs
Session close — the main use	the user, or the model on a concrete end signal (Rule 7)	nothing; this is the default below
Mid-session checkpoint — before /clear, a topic switch, or when the context is getting heavy	the user	the session goes on afterwards. ## In flight is often not "None" — say exactly where the work stopped. Half-done edits stay uncommitted and are named (## Commit step 3)
End of a /iyu:run-cycle run	run-cycle, as its last step	the End-of-Run Report is already the run's chat report — read it as evidence (step 2) and keep your own chat report to a few lines pointing at HANDOFF.md. The run's cycles already updated STRANDS.md

Every occasion ends the same way, too: once HANDOFF.md is written and committed, the conversation is no longer needed to continue. Close the report with one line saying so — the context can be cleared, and /iyu:resume picks up from HANDOFF.md.

Why this exists separately

A session that is not a cycle run ends the way a run does: work happened, the roadmap no longer matches reality, decisions are pending, and the next scope lives only in a conversation that is about to disappear. /iyu:run-cycle ends each run by invoking this skill rather than carrying its own copy of the closeout, so both paths produce the same HANDOFF.md.

This skill is that closeout, detached from the cycle machinery. It shares its definitions with run-cycle rather than restating them: continuity-docs.md is the single source for where the documents live, what belongs in each, the hygiene pass, and how next scope is derived, and release-cadence.md is the single source for where release work sits in the order. Read both first — this file only adds what is specific to closing a session.

Briefing pending decisions is /iyu:resume's job, not this skill's. A briefing is analysis aimed at whoever resumes; produced here it would be written once at close and then sit, possibly staling, until someone acts on it. /iyu:resume grounds the same decision in the repo as it stands the moment someone is about to act on it, and it is the one place a decision gets written back the instant it is made. This skill's job stops at naming what is undecided (step 6) — cleanup and continuity-doc upkeep, nothing more.

Scope

$ARGUMENTS, when given, narrows what to cover (a submodule, a phase, "just the decisions"). Without it, cover the whole session.

Process

1. Resolve the continuity root

Per continuity-docs.md §1. Resolve before reading or writing anything. In an umbrella repo, pick the root covering the code this session touched — and if the session touched several submodules, write one handoff per root rather than merging them into whichever was resolved first.

2. Reconstruct what happened — from evidence, not memory

The conversation may already be compacted, and it is not the record. Read the actual traces:

• git log / git status / git diff --stat since the session started
• The existing HANDOFF.md and ROADMAP.md — what did they claim, and is it still true?
• The most recent cycle-logs/cycle-*.md, if the project runs cycles — its Carry-Forward, ledgers, and Next-Cycle Scope are inherited obligations, not history. At the end of a run, also that run's RUN-SUMMARY-*.md block: its deferred (L2) decisions feed step 6's "Waiting on you", and its self-made (L1) decisions feed "Decided this session"
• Any <root>/issues/ drafts written this session
• <root>/stages/stages.json and its newest evidence/ file, if a stage contract exists (stages.md). Record the open stage and its progress (scenarios passing x/y, latest verdict) under ## In flight; record any owner_decisions still open under ## Waiting on you with the stage each one opens. Never copy scenario text into the handoff, and never edit the contract — it is not a continuity doc.
• The project's external inbox, if it defines one (continuity-docs.md §6) — an item that arrived during the session belongs in the handoff even though nothing in git mentions it
• The existing ## Decided this session entries in HANDOFF.md, if /iyu:resume already recorded one earlier in this same session — carry these forward as fact, not something to re-derive; a decision /iyu:resume wrote back the instant it was made may leave no distinguishing git diff to reconstruct it from. An entry marked already applied is applied to ## Next only — a confirmed reorder still has to be carried into ROADMAP.md's phase order here (step 5), but do not re-apply it to ## Next, which already holds it

Unobserved data stays "unknown". A handoff asserting a test passed, when no one ran it, is worse than one saying "unverified" — the next session builds on it. If something matters and is unknown, say so and name the command that would settle it.

3. Apply the hygiene pass

Per continuity-docs.md §3, in full: migrate every completed item out of ROADMAP.md (including pre-existing leftovers) into HISTORY.md (archiving overflow past its live window), rewrite HANDOFF.md to current + next only, update STRANDS.md (the same transition procedure run-cycle applies per cycle, applied here per this closing session — record the unit as session-{YYYY-MM-DD}, counted once per the rule in §3 step 4, so a second handoff the same day and a handoff at the end of a run add nothing), settle the entries under ## 진행 중 that nothing advanced for over 14 days (continuity-docs.md §3 step 4 f: graduate, stop with a resume condition, or keep with a dated reason), then compress it (archiving overflow past its live window; ## 진행 중/## 중단됨 are never archived), keep the > History: link — then run the structural checks (continuity-docs.md §7) on the result by running the script: sh "${CLAUDE_SKILL_DIR}/../_shared/scripts/docs-lint.sh" <root>. Run it again after steps 5–6 have written their part, before ## Commit: an error-class failure (FAIL, exit 1) is fixed, never committed. Its WARN and UNCHECKED lines, and any failure the rules forbid repairing, go in ## State of play.

This is the step that makes the skill worth running repeatedly. The docs converge toward remaining-work-only on their own, without anyone scheduling a cleanup. It is also what keeps STRANDS.md accurate on the majority of sessions, which close via this skill rather than run-cycle — a session that finishes a phase graduates its strand in the same pass that migrates the phase to HISTORY.md.

4. Derive the next scope

Per continuity-docs.md §4 — carry-forward defects, then mid-session discoveries, then emergent scope across the user / developer / operator lenses, then the backlog. Tag each candidate autonomous-eligible or discussion. When the front of ROADMAP.md is blocked, ## Next descends the order to the startable phases behind it (§4, order is not a gate) — never only its first few items.

Scope concretely for one next session, not five. Anything further out stays a phase-level direction in ROADMAP.md. Concrete scope for sessions you cannot yet know about is the same failure run-cycle guards against with its no-cycle-numbers rule.

Step 5 then decides where the rest sits — deriving the next item and ordering the remainder are different jobs, and skipping the second is how a release ends up scheduled mid-phase.

## Next still empty after this — carry-forward, mid-session discoveries, and the backlog all came up empty. Write the goal-gap review (§4) as the next session's scope — one line; the review itself is the next run's work, not this skill's — and name /iyu:backlog-discover as the pointer for the wider, outward-looking lanes. Do not generate options, a cross-lens read, or a recommendation here; that four-part briefing is resume's job (rule 5 already reserves it for resume, never handoff). This mirrors the closing line run-cycle's End-of-Run Report and resume rule 9 already carry, so all three skills point the same way when the backlog runs dry.

5. Re-order what remains

Deriving what comes next is only half of it. The other half is what order the rest sits in — and the item that most often ends up in the wrong place is the release.

Apply release-cadence.md in full:

• §2, the placement test — for any push/publish/release item in the backlog, check what remains that would touch the same consumer-facing surface. Work still pending on that surface means the release belongs after it: publishing mid-phase buys a version the next few items obsolete, and every pushed pipeline spends a shared CI budget. Finished work that consumers are waiting on pushes the other way. When the two genuinely conflict, that is a decision for step 6's "Waiting on you", not one to settle here. A deferred release gets a frozen batch at its marker — the items known now that it waits on; an existing marker's batch is kept, not re-cut.
• §5, a held release from a run — when /iyu:run-cycle's release review held a granted release (its Release review: held — … line in the run's RUN-SUMMARY-{date}.md: batch open, no receiver, or the interval not passed), write the marker into ## Next at its boundary with the batch and what held it — for the interval, the earliest date — and the act into step 6 as a one-line owner-gated entry. The gate itself is placed, not asked about. That marker is the gate the next run fixes at its start.
• §3 — follow the project's declared cadence; if there is none, infer it from tags and release history and say that you inferred it.
• §4 — the outcome is an edit to the order in ROADMAP.md/HANDOFF.md, with a one-line reason at the marker (— after Phase 3; Phase 3 changes the same CLI output). A paragraph of reasoning is advice the next session skips; a reordered list is what it reads first.

The same test applies to ordinary items when one obviously blocks another, but the release is the recurring case: it is easy to add "release" the moment work feels done, and then it sits in the middle of a phase that will change the same surface again.

Report what moved. A silently reordered backlog is indistinguishable from drift. And reorder only — adding, dropping, or rescoping items is separate work with its own rules.

6. Flag the decisions — name them, don't brief them

Two lists, kept apart because they behave differently:

• Waiting on a human — irreversible or human-only decisions, plus anything blocked on a resource (a credential, an access grant, an external dependency).
• Decided along the way — reversible choices made during the session that carried a real trade-off. Each with its alternatives, the trade-off, and a one-line "to correct: <the reverse action>". Presenting these is what makes deciding-then-reporting safe rather than sneaky. Pure taste choices are not recorded.

Before writing any "waiting on you" entry, run the self-unblock check: is the resource actually missing (look, don't assume), and does a governing doc, an accepted issue, or a prior decision already answer the question? An assumed blocker parks work that could have proceeded.

Apply decision-briefing.md §1 for the entry shapes — but stop at naming, not briefing:

• Resource-blocked entries keep their short factual form (§1): blocker · what was tried · what would unblock it. This is a fact, not a decision, so it is written here in full, same as always.
• Decision-class entries get one line — plus the two facts every entry carries (below): the decision, phrased so it can be answered. Do not generate options, a cross-lens read, or a recommendation here — that analysis is /iyu:resume's job, done fresh against the repo as it stands when someone is actually about to act on it, rather than produced now and left to stale until then. The flag is a placeholder for /iyu:resume to brief and decide — it is not a question addressed to the owner, so do not phrase it as one ("A or B?"); name what is being chosen.
• An owner-gated act (push, publish/release, GitHub issue registration, a major-version bump) whose underlying choice is already settled is resource-blocked, not decision-class — the owner is the resource: blocker = the gate · tried = the decision (pointer to it) · unblocks = approval to run the act. Do not re-flag the settled choice.
• An unanswered criterion request left by /iyu:resume (the criterion at fault · proposed revision · decision taken under it) carries over as-is. It is not a decision to re-flag, and dropping it loses the one question the owner still owes.
• Recommendable + reversible → not here at all. If you can already see the answer and it's reversible, that is not a pending decision — decide it, proceed, and record it under Decided along the way instead. The one-line-flag format makes it cheap to escalate; that is exactly why it must not become the default for anything you could have just decided.
• Nothing to decide → say "None". If everything remaining can be carried autonomously, that is the finding, and it is a good one. Never manufacture a decision to fill the section.

If the project already uses decision IDs (HD-01, D-03, …), continue that numbering rather than starting a scheme of your own.

Every entry, whatever its shape, carries two facts — they are what lets a reader see what a gate holds up and how long it has stood, and neither is briefing:

• Registered — the date the entry first appeared. A carried-forward entry keeps its original date through every rewrite; resetting it hides exactly the gates that have waited longest. It keeps every other field it already has, too — /iyu:resume's Default and Meanwhile included.
• Blocks — the ## Next / ROADMAP.md items that cannot move until it clears, by ID or title. "Nothing" is a valid answer and worth knowing.

An entry that clears leaves the section — HANDOFF.md is current state, so removal is the resolution, and the outcome goes where §2 of continuity-docs.md homes it. /iyu:resume adds Default and Meanwhile to the entries it leaves standing; do not write them here.

Output

<root>/HANDOFF.md, rewritten:

# HANDOFF
> History: [HISTORY.md](HISTORY.md)

**Updated**: {YYYY-MM-DD} · **Root**: {resolved root}

## In flight
{What is half-done right now, and where exactly it stopped — the file, the step, the next command.
"None" if nothing is half-done. A mid-session checkpoint is read by this same session after `/clear`,
so this is the section that has to be exact.}

## Next
{Concrete scope for the next session — from carry-forward, discoveries, or an autonomous-eligible
emergent candidate. Anchored to a ROADMAP phase. One session's worth.}

## Waiting on you
{"None" — the right answer whenever everything left can be carried autonomously — or entries in the
two shapes below: the first decision-class (flagged, not briefed — `/iyu:resume` briefs and decides it), the
second resource-blocked.}

### {HD-01} {the decision, in one line — no options, no recommendation; `/iyu:resume` briefs and decides this next}
- **Registered**: {YYYY-MM-DD} · **Blocks**: {item IDs, or "nothing"}

### {HD-02} {what is blocked}
- **Registered**: {YYYY-MM-DD} · **Blocks**: {item IDs, or "nothing"}
- **Blocker**: {the missing credential / access / dependency}
- **Tried**: {what was actually attempted}
- **Unblocks**: {the specific thing you need}

## Decided this session
{Reversible self-made decisions: decision · trade-off · to correct. Or "None". When the project
keeps a decision ledger, the entry IDs and a link instead (continuity-docs.md §2).}

## State of play
{Build/test/lint status with the actual output, or explicitly "unverified". Branch, the **post-commit**
`git status` (see ## Commit below) — "clean", or the specific files still uncommitted and why.
Structural checks (continuity-docs.md §7): "passed", or each warning and unrepairable failure by code.}

Plus: ROADMAP.md with completed work removed (hygiene pass) and its remaining phases in the order step 5 settled on, and HISTORY.md with the completed work appended.

Then report the same five sections in chat — the file is for the next session, the response is for the person reading now (at the end of a run, a few lines instead: the End-of-Run Report already said it). End with the one-line pointer: the context can be cleared now, and /iyu:resume continues from HANDOFF.md. Carry the flagged decisions into the response too, exactly as one-liners; do not improvise options or a recommendation in chat that step 6 deliberately left for /iyu:resume to produce later.

Commit

Run this after the docs above are in their final form — it commits them too. The goal is git status clean when the skill finishes, and that includes work this skill did not create: pre-existing uncommitted changes already sitting in the tree when the session started (leftover from an earlier session that never got committed) are in scope, not just this session's own edits.

1. Survey everything, not just what this session touched. git status / git diff --stat — include hunks that predate this session's first tool call.
2. Group into logical units and commit what you can confidently attribute. Follow the project's own message convention (recent git log); use its commit skill if one is available instead of hand-rolling the message. Don't commit file-by-file, and don't fold unrelated units into one commit — same anti-fragmentation bar run-cycle applies at its own commit boundary. This includes the handoff's own edits (HANDOFF.md, ROADMAP.md, HISTORY.md, STRANDS.md, any issues/ drafts written this session) as their own logical commit, typically last since it describes everything before it.
3. Do not guess at the unclear. A change you cannot confidently attribute — unfinished work, an ambiguous partial edit, something you can't tell is safe to bundle or is even meant to be committed — is not committed. Leave it as-is and report it by name (file, what's ambiguous, what would resolve it) in "State of play" instead of folding it into a commit or a message that guesses at intent. A wrong guess here is worse than an honest "left uncommitted, because —".
4. Never push, never open a PR. Commit only. Whether the tree ends up clean or not, push and PR creation stay the human's call (global git policy) — this skill's cleanliness goal is about local history, not what leaves the machine.
5. The report carries the real result. "State of play" states the actual post-commit git status, not an aspiration — if something is still uncommitted, that is itself a finding to hand to whoever reads the handoff next.

Rules

1. Remaining work only. Completed work belongs in HISTORY.md. Every run enforces this, not just runs where something was completed.
2. Evidence over assertion. Test/build claims carry their output or are marked unverified.
3. Commit toward a clean tree, but never guess. See ## Commit — every logical unit you can confidently attribute (this session's work, pre-existing uncommitted leftovers, and the handoff's own doc edits) gets committed; anything ambiguous is left alone and reported instead. Never push.
4. Do not implement. If step 2 surfaces a defect, record it — fixing it starts a new session's work and leaves the handoff describing a state that no longer exists.
5. Flag, don't brief — but only where a decision exists. A decision-class entry leaves as one line naming the choice; generating options, a cross-lens read, or a recommendation here is /iyu:resume's job, not this skill's. An empty section is a complete one: if nothing left needs the human, "None" is the finding, not a slot to fill. And if you can already see the answer and it is reversible, it belongs in "Decided this session", not here.
6. One root per handoff. In an umbrella repo, several submodules touched means several handoffs, each in its own root.
7. Model-invoked runs announce first. When this skill starts without an explicit user invocation (/iyu:handoff) — including when /iyu:run-cycle invokes it at the end of a run — say in one line that a handoff is running and why, before touching any file — the rewrite is reversible, but a silent one still surprises whoever is reading the conversation.
8. Point, don't brief, when ## Next is empty. Scope the goal-gap review as next and name /iyu:backlog-discover; do not produce options, a cross-lens read, or a recommendation — see step 4. That stays resume's job.