docs: act on pilot feedback — branch tables, wayfinder, deader prose

Encode a new rule in writing-docs.md: a multi-way branch goes in a table
or a list, never a paragraph the reader has to read in full.

- to-spec: trigger becomes a table; stop implying the tracker must be
  remote, since local markdown is supported out of the box.
- prototype: wayfinder is the largest consumer (prototype is one of its
  four decision-ticket types); the ask-matt handoff round trip is
  demoted to one line.
- handoff: trigger becomes a table; dead prose throughout.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

docs/engineering/prototype.md

@@ -10,6 +10,8 @@ Type `/prototype`, or the agent reaches for it automatically when a task fits.
 
 Reach for it the moment you hit a question you can't settle by talking — a state machine whose edge cases you can't hold in your head, a screen you can't picture until you see three versions side by side. Grilling sessions balloon on exactly these questions: the agent rephrases, you guess, and the scope grows to fill the uncertainty. Stop grilling, build the throwaway version, look at it, then answer in one line. If instead something already built is misbehaving and you want to know why, use [diagnosing-bugs](https://aihero.dev/skills-diagnosing-bugs) — prototyping explores what to build, not why the built thing is broken.
 
+You will also arrive here without choosing to. [wayfinder](https://aihero.dev/skills-wayfinder) files `prototype` decision tickets on its map, and working one is this skill.
+
 ## Two branches
 
 The question picks the branch, and the branches produce very different artifacts:
@@ -42,7 +44,7 @@ Known, and it is a naming problem. `prototype` is a generic, appealing word that
 That is a different artifact wearing this skill's name. A prototype here is scoped to one question, and "what is the whole app?" isn't one. A full-app prototype has no natural stopping point, so it becomes the production app by momentum: the cleanup pass never happens, and code written under prototype rules — no tests, no error handling — ends up in front of users. If you need a sales demo, build it deliberately as a demo and be explicit that none of it is production. If you need to settle a design question, cut it down to that question.
 
 **How do I run it in its own session?**
-That is the step-2 detour in [ask-matt](https://aihero.dev/skills-ask-matt)'s main flow: [handoff](https://aihero.dev/skills-handoff) out of the thread you're in, open a fresh session against that file, `/prototype` there, then `handoff` the conclusions back and reference them from the original thread. A prototype lives in its own directory and generates a lot of context you don't want in the thread that asked the question — which is exactly what the handoff bridge is for.
+A prototype lives in its own directory and generates a lot of context you don't want in the thread that asked the question, so run it somewhere else and bring back only the answer. [handoff](https://aihero.dev/skills-handoff) is the bridge in both directions.
 
 **Isn't this the fastest possible way to burn tokens?**
 It can be, if you prototype questions you could have answered by talking, or let one prototype sprawl across a whole feature. The comparison that matters isn't tokens against zero; it's tokens against building the wrong state model and finding out after it has production callers. Keep the question narrow and the run short, and the spend stays proportionate.
@@ -58,6 +60,8 @@ It can be, if you prototype questions you could have answered by talking, or let
 
 ## Where it fits
 
-`prototype` is a **reach-for-it-anytime standalone** — you drop into it to settle one design question, then drop back out. It is also the named detour in step 2 of the main flow: the escape hatch for when a grilling session hits something it cannot talk its way to.
+`prototype` is a **reach-for-it-anytime standalone** — you drop into it to settle one design question, then drop back out — and it is also machinery another skill runs on.
 
-That is its closest relationship. [grill-me](https://aihero.dev/skills-grill-me) and [grill-with-docs](https://aihero.dev/skills-grill-with-docs) answer grillable questions; the ungrillable ones — how should this feel, does this model hold up — come here instead, and the one-line answer goes back into the interview. Downstream, a validated state model or UI direction becomes settled input for [to-spec](https://aihero.dev/skills-to-spec), which can inline the decision-rich snippet the prototype produced rather than describing it in prose. For anything else, [ask-matt](https://aihero.dev/skills-ask-matt) routes you over the whole set.
+Its largest consumer is [wayfinder](https://aihero.dev/skills-wayfinder). A wayfinder map is made of **decision tickets**, and `prototype` is one of the four types a ticket can be: the one used when the blocking question is "how should this look" or "how should it behave", which no amount of discussion resolves. Wayfinder raises the fidelity of a foggy discussion by making something concrete to react to, and this skill is how that concrete thing gets built. A prototype ticket is resolved by the answer, and the prototype is linked from the map as an asset.
+
+The other neighbours are upstream and downstream of that. [grill-me](https://aihero.dev/skills-grill-me) and [grill-with-docs](https://aihero.dev/skills-grill-with-docs) answer grillable questions; the ungrillable ones come here instead, and the one-line answer goes back into the interview. Downstream, a validated state model or UI direction becomes settled input for [to-spec](https://aihero.dev/skills-to-spec), which can inline the decision-rich snippet the prototype produced rather than describing it in prose. For anything else, [ask-matt](https://aihero.dev/skills-ask-matt) routes you over the whole set.

docs/engineering/to-spec.md

@@ -8,11 +8,18 @@ It does not interview you. By the time you reach for it the deciding is already
 
 You invoke this by typing `/to-spec` — the agent won't reach for it on its own.
 
-Reach for it when the build is too big for one agent session and has to survive being split across several. That is the whole trigger: if grilling settled everything and the work fits in one context window, skip the spec and go straight to [implement](https://aihero.dev/skills-implement). If you haven't aligned yet, grill first with [grill-with-docs](https://aihero.dev/skills-grill-with-docs). Once the spec exists, [to-tickets](https://aihero.dev/skills-to-tickets) slices it.
+Reach for it when the build is too big for one agent session and has to survive being split across several. That is the whole trigger:
+
+| Where you are | What to run |
+| --- | --- |
+| You haven't decided anything yet | [grill-with-docs](https://aihero.dev/skills-grill-with-docs) first |
+| Decided, and the work fits one context window | [implement](https://aihero.dev/skills-implement) — skip the spec |
+| Decided, and the work spans several sessions | `/to-spec`, then [to-tickets](https://aihero.dev/skills-to-tickets) |
+| A [wayfinder](https://aihero.dev/skills-wayfinder) map has cleared | `/to-spec #<map_issue>` |
 
 ## Prerequisites
 
-`to-spec` publishes into your tracker, so [setup-matt-pocock-skills](https://aihero.dev/skills-setup-matt-pocock-skills) must have configured the tracker and the triage-label vocabulary for this repo first. There is no local file: the spec is written straight into the tracker as an issue.
+`to-spec` publishes the spec as an issue, so [setup-matt-pocock-skills](https://aihero.dev/skills-setup-matt-pocock-skills) must have configured a tracker and the triage-label vocabulary for this repo first. Either kind works: a real tracker like GitHub, or local markdown files under `.scratch/`, which is supported out of the box.
 
 ## The spec is a decision record
 

docs/productivity/handoff.md

@@ -2,21 +2,30 @@
 
 `handoff` compacts the conversation you are in into a **handoff document** — one markdown file, written to your OS's temporary directory rather than into the workspace, that a fresh agent can read to pick the work up.
 
-What it buys is **portability**, not compression. That is the fact most people miss, and it makes the skill much narrower than it sounds: you need a file only when something has to *travel* — to a new harness, to a new directory, to a colleague, or to a side task you want to fork off without derailing what you're doing. If nothing is travelling, you don't need a handoff. Staying in the session, `/clear`, a subagent and `/compact` all cover the ordinary end-of-phase case, and `/compact` covers it more often than this skill does.
+What it buys is **portability**, not compression. That makes the skill narrower than it sounds. You need a file only when the work has to *travel* — to a new harness, a new directory, a colleague, or a side task you want to fork off. If nothing is travelling, you do not need a handoff: staying in the session, `/clear`, a subagent and `/compact` cover the ordinary end-of-phase case, and `/compact` covers it more often than this skill does.
 
 ## When to reach for it
 
-You invoke this by typing `/handoff` — the agent won't reach for it on its own. Pass a note about what the next session is for and the document is tailored to it.
+You invoke this by typing `/handoff` — the agent won't reach for it on its own. Pass a note about what the next session is for, and the document is written for it.
 
-Reach for it when one of four things is true: you're **swapping harness** (Claude → Codex), moving to a **new directory or repo**, sending the work to a **colleague**, or **forking a side task** you found mid-phase. That list is the whole trigger. For the same-harness, same-directory boundary — you're done grilling and moving to implementation — `/compact` is the move, and [ask-matt](https://aihero.dev/skills-ask-matt) carries the ordered tree that gets you there.
+Four situations are the whole trigger:
+
+| Situation | Why a file |
+| --- | --- |
+| Swapping harness — Claude → Codex | The new harness cannot see the old context |
+| Moving to a different directory or repo | A prototype directory is the common case |
+| Sending the work to a colleague | They need something they can read |
+| Forking a side task found mid-phase | You keep working; a second agent takes the fork |
+
+For anything else — same harness, same directory, you are done grilling and moving to implementation — `/compact` is the move. [ask-matt](https://aihero.dev/skills-ask-matt) carries the ordered tree over all five options at a phase boundary.
 
 ## Branching is the use people skip
 
-The description reads like session resumption — write a summary, end here, resume there — so it gets skimmed past. The fork case is the one worth knowing: you **stay in your session**, and hand the accumulated context to a *second* agent working in parallel.
+The skill's description reads like session resumption: write a summary, end here, resume there. Read that way it looks like a worse `/compact`, so it gets skimmed past. The fork case is the one worth knowing. You **stay in your session** and hand a copy of the accumulated context to a second agent working in parallel.
 
-That's what makes the detour through [prototype](https://aihero.dev/skills-prototype) work. You're deep in a design conversation, you hit a question that can only be answered by running something, and you don't want to burn the thread you built to find out. `/handoff` out to a prototype session, get the answer, `/handoff` back, and reference the return document from the original thread. Two crossings, one live conversation, nothing re-explained.
+That is what the detour through [prototype](https://aihero.dev/skills-prototype) uses. You are deep in a design conversation, you hit a question that only running code will settle, and you do not want to spend the thread you built on finding out. Hand off to a prototype session, get the answer, hand the answer back, and reference it from the original thread. Two crossings, one live conversation, nothing re-explained.
 
-The one-line version, from a reader: `/compact` preserves intent, `/clear` preserves nothing, `/handoff` preserves momentum.
+Three of the five options at a phase boundary preserve different things: `/compact` preserves your intent, `/clear` preserves nothing, `/handoff` preserves the work's ability to move.
 
 ## What travels, and what doesn't
 
@@ -33,7 +42,7 @@ What it deliberately does not carry is anything already written down. Specs, pla
 Three different things being preserved. `/compact` compresses this context and keeps you going in a fresh window — intent survives. `/clear` empties the window and starts from nothing — correct when everything behind you is disposable, and one-way if it isn't. `/handoff` writes a portable file — the work survives the move to somewhere else. Note that all three turn a **primary source** (the conversation as it happened) into a **secondary source** (a summary of it). Continuing is the only move that doesn't, which is why it's the first one to rule out.
 
 **Where did my handoff file go?**
-The temp directory, which is the most-reported friction with the skill: the paths are long, they differ per OS, and on Windows agents sometimes take several attempts to find the right one. Ask for the path back and keep it before you move on. Temp is deliberate — a handoff is a transit document, not an artifact you maintain — but it is transit with a short shelf life.
+The temp directory, which is the most-reported friction with the skill: the paths are long, they differ per OS, and on Windows agents sometimes take several attempts to find the right one. Ask for the path back and keep it before you move on. Temp is deliberate: a handoff is a transit document, not an artifact you maintain. It is not a durable one either — see the next question.
 
 **My handoff vanished between sessions.**
 Some environments clear temp between sessions — Codex is the reported case — and `/private/tmp` goes on reboot. If the next session isn't starting within the hour, or is starting under a different harness, copy the file somewhere durable yourself as soon as it's written. The same applies to anything the document *points at*: a dispatch that references other files in temp is a dispatch the next agent can't follow.
@@ -48,7 +57,7 @@ Analogous, not identical, and `/branch` isn't a shipped skill here — `/handoff
 Ask whether it's true next month. `CLAUDE.md` is standing context about the project, loaded into every session whether it's relevant or not. A handoff is about one piece of work in flight and is dead once that work lands. Facts that keep getting re-explained are a `CLAUDE.md` problem; a half-finished task is a handoff.
 
 **It captures the what, not the why.**
-A fair and repeated criticism. Two things help. Pass the argument — tell it what the next session is for — so the reasoning that bears on *that* is kept rather than flattened. And watch for confident claims the session never actually verified: "X isn't built", "Y is done". The next agent treats the document as a contract and won't re-check, so an unverified belief written as a fact becomes work built on sand. Read the document before you hand it over, and downgrade anything you only assumed.
+A fair and repeated criticism. Two things help. Pass the argument — tell it what the next session is for — so the reasoning that bears on *that* is kept rather than flattened. And watch for confident claims the session never actually verified: "X isn't built", "Y is done". The next agent treats the document as a contract and will not re-check it, so a belief written as a fact becomes a false premise for everything that follows. Read the document before you hand it over, and downgrade anything you only assumed.
 
 **Why is it a skill rather than a slash command?**
 Both work; they suit different situations. As a skill it ships and updates through the same install path as everything else here, which is what makes it shareable — the constraint that the agent won't fire it itself is set by its frontmatter rather than by the mechanism.