/handoff

name: handoff
description: "Generate structured handoff materials for offline human tasks (interviews, observations, outreach). Creates actionable briefs with phone-friendly capture templates."
metadata:
  instruction_budget: "47"
  framework_dependency: "mycelium"
  framework_dependency_note: "This skill is designed to run within the Mycelium framework (https://github.com/haabe/mycelium). Standalone use will skip the canvas state, theory gates, and harness behavior the skill assumes. Install: /plugin install mycelium@haabe-mycelium."

Handoff Skill

Generate structured materials for tasks the human does offline. Bridges the gap between "we need external evidence" and "here's exactly what to do and bring back."

Preflight: Read target canvas file(s) before any Write/Edit

**Hard rule.** Before issuing `Write` or `Edit` against any `.claude/canvas/*.yml`, use the **Read tool** on that file in this session. Claude Code's Read-before-Write check requires the `Read` tool specifically — `cat`/`head`/`grep` via Bash do NOT satisfy it.

**Edit vs Write — different cost profiles** (verified 2026-05-14):

• **`Edit`** (exact-string replacement): `Read` with `limit: 1` satisfies the check at ~50 tokens. State-tracking is per-file, not per-byte — subsequent `Edit` calls work anywhere in the file. Use this for partial updates against large canvas files (e.g., `purpose.yml` at 800+ lines).
• **`Write`** (full replacement): do a **full Read** first. Write obliterates the file; you should see what you're about to replace. The `limit:1` shortcut is *not* appropriate here.

**ID-bearing entries — scan the ID space before assigning** (added 2026-05-15, v0.23.19): When adding a new component, opportunity, solution, or any other ID-bearing entry to a canvas file, run a Bash grep first to confirm the next ID in your prefix sequence is actually free:

grep -o "<prefix>-[0-9][0-9]*" .claude/canvas/<file>.yml | sort -u -t- -k2 -n | tail -3

Replace `<prefix>` with the canvas's ID prefix (`comp` for landscape, `opp` for opportunities, `sol` for solutions, `ht` for human-tasks, etc.). Then pick the next free integer, **matching the zero-padding already used in that file**. The sort is NUMERIC (`-t- -k2 -n`) rather than lexical, and that is not pedantry: a plain `sort -u` orders `ht-1` after `ht-080`, so on a canvas with inconsistent padding it reports the wrong maximum and the next ID collides. Verified on the dogfood repo 2026-08-13, where lexical sort returned `ht-1` as the highest human-task ID against an actual `ht-080`. `grep -o` is also deliberate: it matches IDs wherever they appear, including cross-references and prose, so an ID that was promised somewhere but not yet defined is not handed out twice. `validate_canvas.py` has a per-file duplicate-ID check (it reports `duplicate id '<id>'`) that catches the failure on CI, but a duplicate can persist in the working tree for days if CI isn't run between edit and discovery; that happened on 2026-05-15, when a duplicate ID was created in `landscape.yml`.

Original failure mode: anti-pattern #7 instance #5, 2026-05-09 — agent conflated Bash `head` with the Read tool, lost ~14k tokens to a Write-fail → remedial-full-Read → re-Write loop. The `limit:1` discipline (graduated 2026-05-14, v0.23.18) prevents the second-order cost where the agent *correctly* follows the rule but full-Reads every time. The ID-scan discipline (graduated 2026-05-15, v0.23.19) prevents the related class where the agent reads enough of the file to satisfy the Edit check but not enough to see existing ID assignments — kin to anti-pattern #8 (Stale State Read).

If this skill writes to multiple canvas files, register each one first (limit:1 for Edit-only paths; full Read for Write paths) AND ID-scan any prefix you intend to assign.

See `${CLAUDE_PLUGIN_ROOT}/engine/agent-operating-contract.md` *Canvas writes — Read before Write* for the canonical rule.

When to Use

• When the Evidence Gate source ratio nudge fires (all evidence is desk-derived)
• When `/mycelium:diamond-progress` identifies a need for external validation
• When the agent identifies an assumption that requires human contact to validate
• When the user asks "what should I do next offline?"
• **Proactively**: whenever a human-executable task is identified, offer to run `/mycelium:handoff` before the user asks

Workflow

1. **Identify the evidence gap**:

• Read active diamond state from `.claude/diamonds/active.yml`
• Check canvas provenance for `source_classes` distribution
• Identify which canvas sections lack `external_human` or `external_data` evidence
• State the gap plainly: "We have [N] evidence sources but none from real conversations."

1b. **Read the channel map before naming a channel** (added 0.191.0). If the brief will be an `outreach` or names any channel, open `.claude/canvas/go-to-market.yml#channel_intelligence` first and state, in the brief, what the record shows worked and what was ruled out, with the entry's date. Posture rulings recorded there bind the brief (a channel ruled inbound-only is not proposed as outbound). If the file has no such section, say so in the brief: "no channel ledger on this canvas" is a fact the reader needs, and it is not the same as "no channel has been tried". Why: on 2026-08-25 a dogfood session proposed acquisition channels for hours and never retrieved a ledger that already held 18 of 24 standard channels with decisions attached. The surface registry (`engine/surface-registry.yml#channel-evidence`) declares this skill as that ledger's reader, and `check_surface_registry.py` fails if this step stops naming the file.

2. **Determine task type**:

• `interview` -- structured conversation with a target user/stakeholder
• `observation` -- watch someone use a competitor product or perform a task
• `survey` -- collect structured responses from multiple people
• `usability_test` -- test a prototype or concept wi