Handback

handback — end an arc with a work order, not a lab notebook

Spec: broomva/workspace → docs/specs/2026-08-18-agent-handback-contract.html (BRO-2179).

Why this skill exists

Measured over 994 Claude Code transcripts (analysis set: 100 sessions of ≥6h wall-clock and ≥150 assistant turns):

The two blocker rows differ on purpose. The broad count (31) includes messages that merely mention being blocked — "the pre-commit hook blocked it", "#381 remains blocked by the hang". The narrow count (18) is the defensible one: a terminal message that stops the arc on a person. The enforcement gate keys on the narrow definition, because refusing a healthy receipt that happens to contain the word "blocked" would fight the operator.

The ask usually exists. It is placed last, written in the indicative ("Not merged — auto-merge correctly blocked"), and carries no default, so the arc dies on it — median 2.4h of stalled arc-time behind such a message, 25 of them overnight-length.

Rule zero — asking is the last resort, not the interface

No ask may exist until every rung below has been tried and recorded. A row with an empty exhausted list is a defect, not a question.

Rung 6 is where most asks should die. A choice that can be undone with one commit does not warrant stopping an arc; it warrants a line in the receipt. Only actions that are irreversible, externally visible, or spend money may reach rung 7 without a default — and the ask must say which.

Rule minus-one — never stop the arc while an unblocked lane remains

Blocked is a lane state, not an arc state. When an ask fires: park the lanes it gates, emit the ask (push it if outside the waking window), and continue on the next unblocked lane. Run handback only when the unblocked set is empty. An arc that halts with runnable work left is the failure this skill exists to prevent.

The shape — six blocks, always in this order

"Always in this order" constrains order, never presence. A block with no content is omitted, not rendered empty — an empty 🔀 block would assert that nothing was decided, and an empty ⛔ block would assert that nothing is blocked. Only the receipt is unconditional.

## ⛔ Blocked on you — N items, ~M min
   table: # | ask (imperative, addressed to "you") | unblocks | if you say nothing
   a decision row lists options A/B/C, one marked suggested, each with its cost
   plain language only; hard cap 7 rows, ranked by what each unblocks

## ▶ Running meanwhile
   what is still executing, or what ran with zero input from you

## ✅ Shipped
   PR table. One line each. No narrative.

## 🔀 Decided for you — N choices, least-confident first
   table: # | what I decided | why it was mine to take | undo
   rendered from the ledger's `decisions:` list, never free prose
   every row carries its one-line reversal — that is what made it safe not to ask
   hard cap 7, same as the ask block; overflow counted in the header

## 📋 Receipt — the nine items, unchanged
   1 dep chain · 2 plan vs done · 3 parallel streams · 4 files changed · 5 PRs
   6 deploys · 7 validation · 8 merge result · 9 follow-ups

## 📎 Detail → docs/handoffs/<arc>.md
   the NARRATIVE lives there: what happened and why, the review sagas, the
   corrections. That prose is what this contract displaces.

The ten rules

Each is derived from a measured failure, not a style preference.

1. The ask block is first. Not a "Your call" section at 80% depth. Measured: the ask lands around p80 of the message.
2. Every row is an imperative addressed to "you" — a command to run, a link to click, a value to paste, or a one-line answer to a closed question. Measured: 0 of the 18 halting messages contained a conforming ask block.
3. A decision row offers options, not an open question. Two or three concrete choices, each with its consequence in one line, one marked as the recommendation. Never "what should we do about X?" — always "A, B, or C; I suggest B because …".
4. Plain language, no internal vocabulary. No primitive numbers, no gate names, no acronyms, no ticket ID standing in for the question. If a term needs the spec to understand, it does not belong in an ask.
5. Every row carries a default. "If you say nothing, I do X." A row with no safe default must say so explicitly and name what it costs. Measured: 5% stated a default. Silence is otherwise fatal.
6. Every row is self-contained. Answerable without opening a ticket. The ticket ID is a reference for later, never the carrier of the question. Measured: 58% used a ticket as the carrier; median 1 ticket, up to 13.
7. Rows are ranked by what they unblock, stated in the row — "unblocks 9 of 18 rows", "unblocks 1 lane". A tired person answering one thing should be answering the right one.
8. Hard cap: 7 rows. More than seven means the arc should have asked earlier. Overflow goes to the ledger, with the total stated in the header ("3 of 11 shown").
9. The nine-item receipt stays, underneath the asks. It is structured and proves the work. What this contract displaces is the free-form narrative — that moves to docs/handoffs/.
10. The ask block ends with the reply already drafted — one line per row, numbered to match. A copy-pasteable skeleton, one line per row, recommendation pre-filled — so answering is an edit, not a composition. Rules 2–6 fix what a row says; none of them lowers the cost of replying, and a perfectly-formed ask still stalls if answering it means composing prose at 1am. Reacting beats imagining: hand the reader something to strike through, not a blank box. The skeleton is generated from the rows: if it has four lines and the table has five, the fifth ask is one the reader is never prompted to answer — a silent drop dressed as a convenience.

The 🔀 block — what rung 6 owes the human

Rung 6 is where most asks are supposed to die: take the reversible default, log it, tell the human afterwards. For as long as this contract defined five blocks, there was nowhere for that last clause to land — the ladder told the arc to decide and say so, and the message shape had no room for it. Every silent-but-correct decision therefore looked identical to no decision at all, while the user still inherited it.

The 🔀 block is that room. It is not an ask block: nothing in it is a question, and the arc did not wait for any of it.

Where each verdict surfaces, so nothing is duplicated and nothing is dropped:

Consequence worth stating plainly: because the schema forces an irreversible choice to be needs-user, no valid ledger can render one in 🔀 at all. The renderer keeps a defensive branch for a ledger nobody validated — an empty undo column would read as "no undo needed", the opposite of the truth — but on a valid ledger that branch is unreachable.

sound is not skippable. The temptation is to list only the shaky calls, but a confident decision the user never made is still architecture the user now owns. Trivial discretion — internal naming, cosmetic calls — compresses to a one-line count; everything load-bearing gets a row.

Anti-patterns

Composition

• handoff — same arc, different reader. handoff writes docs/handoffs/YYYY-MM-DD-<arc>.md for the next agent; handback writes the chat message for the human. A stopping arc usually produces both, and the handback's Detail block links to the handoff.
• autonomous — supplies the nine-item receipt that block 4 renders, and owns the pre-flight that builds the ask ledger.
• persist / governed-autonomy-loop — a parked lane is a lane the next iteration's PROMPT.md omits; handback fires only when none remain.

References

• references/template.md — copy-paste skeleton with a worked example.