Handoff tracker

HandOffTracker

When work passes between models and the operator can't always see what's next, the model that's stopping owes the operator a decision, not a dead end: the options it can see, a recommendation, and the choice left to the operator.

Why this exists

The operator steers the project but often can't see the road — they may not read the code, and at any given handoff the right next step may genuinely be unclear to them. The model can see the road, but it should not unilaterally drive: control and authorship belong to the operator. That leaves two bad default behaviors and one good one.

The model drives autonomously → the operator loses both control and any record of having authored the work. The model hands off with a bare "what now?" → it strands an operator who, by definition, can't generate the options themselves. HandOffTracker is the third path: informed delegation of choice. The model that can see the road surfaces the real options and recommends one; the human makes the call. Three things fall out of doing this honestly: the operator is never stranded at a fork; the surfaced-but-untaken options become a recovery map when the chosen path fails; and the clean split between model-recommended and operator-chosen is a precise record of where human judgment actually steered.

The core move: hand off a decision, not a dead end

At every genuine fork — where the next step is unclear or consequential — the outgoing model produces a Decision Handoff with four separated parts:

• Options it can see — real, distinct, mutually exclusive next moves.
• Recommendation + why — the model's judgment, labeled as the model's, including the cost of the recommended path and what would make a different option correct.
• Operator's choice + why — the human's judgment; left blank for the operator to fill. This is the steering act.
• Outcome — filled in later, so the fork becomes navigable for recovery.

The separation is the whole point. The model generates and advises; the human decides; both are recorded distinctly, so later you can always tell which was which. Format in references/decision-handoff-format.md.

Integrity rules — a rigged menu destroys everything at once

The entire value depends on the option set being honest. A corrupted menu doesn't just mislead the next step — it poisons the recommendation, the recovery map, and the provenance trail simultaneously.

1. Options must be genuine and distinct. Never dress one real option with strawmen to railroad the operator toward a predetermined answer. If there's truly only one viable move, say so plainly — don't manufacture a fake choice.
2. Be honest that the menu is bounded by your view. Surface the options you can see; don't present the menu as exhaustive if you're not sure it is. "These are the moves I can see" is honest; implying completeness you don't have is not.
3. Frame options at the operator's altitude. Describe each in terms of consequences and tradeoffs the operator can actually evaluate, not implementation detail they can't read. Translating the fork into the operator's language is the job — if they could read the code, they wouldn't need the menu.
4. Make the recommendation carry its reasoning. State the cost of the recommended path and name what would make another option right. This is what lets the operator genuinely judge rather than rubber-stamp, and it pre-loads the recovery map.
5. Calibrate confidence honestly. Distinguish "clearly A" from "roughly equivalent, slight lean to A." Don't manufacture false confidence, and don't false-balance a genuinely lopsided choice.
6. Only raise a Decision Handoff at a real fork. Unclear or consequential next steps earn one; a forced or obvious next step does not. Don't spam the operator with fake choices — the same residue discipline as everywhere else: surface only what genuinely needs a decision.

Recording: the tracker

Decision Handoffs accumulate into an append-only record that is the operator's orientation, the recovery map, and the provenance trail in one file.

• Keep the open decision — the current fork awaiting a choice — hot and current, at the top.
• Let resolved decisions settle into the history below. Don't force every reader to re-walk the whole tree each turn; the open fork is what the next turn needs, and the resolved history is for browsing and recovery.

If seamkeeper is also in use, this is the same residue economy applied to forks rather than to code. Format and status markers in references/decision-handoff-format.md.

Recovery: returning to the fork

When a chosen path fails, do not silently rewrite the old decision — the failed branch is informative history, not a mistake to erase. Instead:

1. Return to the fork and re-read the original option set and the recommendation's reasoning.
2. Fold the failure in as new evidence. It frequently flips which option is now correct: the concern that made you reject option B may matter far less than the failure mode you just hit on A.
3. Record a new Decision Handoff at that fork — the remaining options, a recommendation updated by the failure, and the operator's new choice.

You return to the fork smarter than you left it, precisely because the menu and the reasons were preserved instead of discarded. Recovery format in references/decision-handoff-format.md.

Provenance: the operator's choices are the authorship trail

Because the model's recommendation and the operator's choice are recorded separately, the file shows exactly where human judgment was load-bearing — most strongly where the operator chose against the recommendation. That trail is defensible evidence of human authorship and the visible texture of real, non-slop work.

One honesty rule governs it: never record a choice as the operator's if the operator didn't make it. A model filling in a choice the human didn't actually make is fabrication, and an inflated presence claim destroys the provenance the way a rigged menu destroys the recovery map. The value is the honesty; an inflated trail is worth less than an honest short one. Extraction note in references/decision-handoff-format.md.

Pairing with seamkeeper (optional)

HandOffTracker is standalone — it governs the operator-facing decision layer and needs nothing else to work. It composes cleanly with seamkeeper, which governs intent inside the code. They are the same fork seen from two altitudes: seamkeeper's in-code rejected: B — why not residue and HandOffTracker's surfaced option set describe the same choice, one in the code and one at the orchestration layer. When both are present, a Decision Handoff can reference the code-level residue it produced and vice versa — but neither depends on the other, and each is complete alone.

A note on this file

This SKILL.md practices its own discipline: it surfaces the real moves, states the reasoning, and leaves nothing in that the reader could already infer. If you extend it, keep the option sets honest and the residue minimal.