docs: rewrite the remaining 18 pages to the four-section standard

One agent per page, each rewriting from its SKILL.md up and running its
own evidence hunt across the wiki, the issue tracker and the unreleased
changesets. Question counts track the evidence: wayfinder earns ten,
resolving-merge-conflicts earns three.

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

docs/productivity/grilling.md

@@ -1,33 +1,87 @@
 ## What it does
 
-`grilling` is the relentless interview that stress-tests a plan or design before you build it. It maps the plan as a **design tree** — every decision branches into the decisions that hang off it — and works that tree in **rounds** until you and the agent share the same understanding.
+`grilling` is the interview loop that stress-tests a plan, a decision, or an idea before anyone acts on it. It maps the subject as a **design tree** — every decision branches into the decisions that hang off it — and interviews you branch by branch until nothing is left silently assumed.
 
-Each round asks the whole **frontier**: every decision whose prerequisites are already settled — the questions it can put to you *now* without guessing at answers it hasn't heard yet. Your answers reshape the tree, pushing the frontier outward, and the next round asks whatever that unblocks. Thirteen questions land in a handful of rounds instead of thirteen. Every question arrives in a fixed shape — numbered and titled behind a `❓` (`❓ **Q1** - **Storage backend**`), then the body, then the agent's recommendation on its own `➡️` line — so a round reads as a scannable list and you can answer it by number rather than by quoting it back; any *fact* the environment can settle it dispatches to a background sub-agent rather than asking you — and it doesn't block on that research, only the questions downstream of it wait. It won't act on the plan until you confirm the shared understanding has been reached.
+It does not ask one question at a time, and it does not ask everything at once. Each **round** asks the whole **frontier**: every decision whose prerequisites are already settled, and nothing else. Two questions never share a round if one depends on the other — a question that hinges on an answer still open belongs to a later round. Your answers settle decisions, the frontier moves outward, and the next round asks what that unblocked. Thirteen questions typically land in about three rounds rather than thirteen.
 
-### Prefer one question at a time?
+## When to reach for it
 
-If the old one-at-a-time rhythm suited you better, keep it. Add a line to your global `CLAUDE.md`:
+Type `/grilling`, or the agent reaches for it on its own when a task fits. It is the only skill in the grilling family that is model-invoked, which is why you rarely type it: usually a skill you *did* type is running it for you.
+
+Typing `/grilling` directly gets you the plain interview and nothing else. Where you want something more than that:
+
+| What you have | Reach for |
+| --- | --- |
+| Any subject at all, no repo, nothing written down afterwards | [grill-me](https://aihero.dev/skills-grill-me) — the same session, under a name the agent will never fire by itself |
+| A codebase to align against, and you want the decisions kept | [grill-with-docs](https://aihero.dev/skills-grill-with-docs) — it writes `CONTEXT.md` and ADRs as it goes |
+| An effort too big to hold in one session | [wayfinder](https://aihero.dev/skills-wayfinder) — it charts a map and runs grilling inside the decision tickets |
+| A question that talking cannot settle — how something should look or feel | [prototype](https://aihero.dev/skills-prototype) — build the throwaway version, then come back |
+| A skill of your own that needs an interview | Invoke `/grilling` from it, rather than writing another interview |
+
+## The round, the frontier, and who decides
+
+Three ideas carry the whole skill.
+
+The **design tree** is the model of the subject: decisions with decisions hanging off them. The **frontier** is the set of decisions whose prerequisites are all settled — the only questions that can honestly be asked yet. A **round** is one frontier, asked in full and answered in full.
+
+Inside a round every question arrives in a fixed shape: numbered and titled behind a `❓`, then the body, then the agent's recommended answer alone on a `➡️` line. That is what makes a round answerable by number — "1 yes, 2 the second option, 3 no, here's why" — instead of by quoting questions back. The format has one known rough edge: the recommendation sometimes argues *against* the question as it was worded, so agreeing with the recommendation means answering "no" to the question. When that happens, answer the recommendation and say so.
+
+The other half of the design is the split between facts and decisions. Facts are the skill's own job: when a frontier question needs something the environment can settle, it dispatches a sub-agent to go and find out rather than asking you. It does not block on that — only the questions downstream of a running exploration wait. Decisions are yours, and it must wait for them. An agent running `grilling` that answers its own decisions has broken the skill, not interpreted it liberally. The session ends when the frontier is empty, and it will not act on what you agreed until you confirm you have reached a shared understanding.
+
+The honest limit: the frontier is the agent's judgement, not a computed graph. It can put two questions in one round and only afterwards discover that one answer should have changed the other. There is no guard against that beyond telling it, which reopens the affected branch in the next round.
+
+## What lives here and what lives in the wrappers
+
+This page covers the mechanism. The things people most often want are documented one level up.
+
+| Question | Where it is answered |
+| --- | --- |
+| The tree, the frontier, rounds, the question format, facts vs decisions | Here |
+| How long a session should run, what to do with a question you can't answer by talking, how to avoid nodding along | [grill-me](https://aihero.dev/skills-grill-me) |
+| What gets written to `CONTEXT.md`, what becomes an ADR | [grill-with-docs](https://aihero.dev/skills-grill-with-docs) |
+
+## Common questions
+
+**Can I go back to one question at a time?**
+Yes, and a large part of the audience does. Add this to your global `CLAUDE.md`:
 
 ```
 When grilling, ask one question at a time.
 ```
 
-## When to reach for it
+The round-based default is genuinely contested. Practitioners who read slowly, who work in a second language, or who use the sequential format as focus scaffolding all report the one-at-a-time rhythm is better for them, and the opt-out is supported rather than tolerated.
 
-Type `/grilling`, or the agent reaches for it automatically when a task fits — this is the underlying primitive, not a user-only entry point.
+**Where did `/batch-grill-me` go?**
+Into this skill. Round-based questioning shipped briefly as a separate skill, then moved into `grilling` itself, so everything built on the primitive — `grill-me`, `grill-with-docs`, `triage`, `wayfinder` — got it at once. There is no `batch-grill-me` to install, and no separate sequential skill either; the `CLAUDE.md` line above is the way back to one-at-a-time.
 
-Reach for it when a plan or design still has soft spots and you want them surfaced before code is written. In practice you usually invoke it through one of its two wrappers rather than by name: for a plain grilling session use [grill-me](https://aihero.dev/skills-grill-me); to have the session also write ADRs and a glossary as it goes, use [grill-with-docs](https://aihero.dev/skills-grill-with-docs).
+**Asking a whole round at once must lose the questions my earlier answers would have raised. Doesn't it?**
+This is the most common objection to the round design, and the frontier is the answer to it: a round only ever contains questions that do not depend on each other, so no answer in a round can invalidate another question in that round. Answers still reshape everything downstream — the next round is recomputed, not pre-written. What you lose is smaller than "all questions at once" implies, and larger than nothing: see the frontier's limit above.
 
-## The decision tree
+**It ran out of questions and started building.**
+A confirmation gate exists precisely for this: the skill is not finished when the frontier empties, it is finished when you say the understanding is shared. Weaker and faster models still break it — this is reported most often on lower-effort or non-frontier models, which collapse "interview until shared understanding" into a couple of questions and an outline. If yours does it, the reliable fix is a line in your own `AGENTS.md` or `CLAUDE.md` telling the agent not to implement without permission.
 
-The mental model is a **design tree**: every plan branches into decisions, and decisions depend on each other. The **frontier** is the set of decisions whose prerequisites are all settled — the only questions that can be asked without guessing. `grilling` asks the whole frontier at once, then recomputes it from your answers, so a round is exactly the batch of questions that *don't* depend on each other. A question whose answer hinges on another still open this round waits for a later round. Asking in frontier-sized rounds keeps the dependency structure intact while sparing you a question-at-a-time drip.
+**It answered its own questions instead of asking me.**
+That is a bug in the run, not the intended behaviour, and it was the reason facts and decisions were separated in the skill's text. It shows up most when another skill runs `grilling` inside a resolve-this-ticket frame, where the surrounding task reads as licence to keep moving. The same constraint is why there is no async mode: people have asked for a variant that reads a GitHub issue and posts one consolidated decision memo, and that is a different skill, because a grilling session that nobody answers has produced the agent's opinion rather than yours.
 
-## Pulled out on purpose
+**Can I cap the number of questions?**
+No, and a cap is deliberately out of scope. Some plans need three questions and some need fifty; a fixed ceiling either truncates the hard case or feels arbitrary on the easy one. Steering in plain language is the intended control — tell it to wrap up, or stop and accept the plan where it stands. If a session is running very long, the cause is usually that the scope was too big; break the work up and grill the pieces.
 
-`grilling` is the **single source of truth** for the interview technique, split out as a model-invoked **primitive** so every skill that needs an interview can reach it instead of reinventing one. [grill-me](https://aihero.dev/skills-grill-me) and [grill-with-docs](https://aihero.dev/skills-grill-with-docs) are its two user-invoked front doors, but [improve-codebase-architecture](https://aihero.dev/skills-improve-codebase-architecture) and [triage](https://aihero.dev/skills-triage) also lean on it to pressure-test their own decisions.
+**I installed `grill-me` on its own and nothing happens.**
+`grill-me` is a one-line skill whose whole body is "run a `/grilling` session", so it needs this skill installed too. The same is true of `grill-with-docs`, which additionally needs [domain-modeling](https://aihero.dev/skills-domain-modeling). Installing the whole set avoids the problem; installing selectively means installing the primitives as well.
 
-Keeping the technique in one place means you can also reach for it directly when you just want the interview — without the ADR-writing or ticket-shaping that its wrappers add on top.
+**`grill-with-docs` ran, but it never loaded `grilling`.**
+A real and unfixed rough edge, reported across harnesses and models: a skill that names another skill does not reliably cause that skill to load, and `grill-with-docs` names two. The tell is a session that asks everything at once with no recommendations attached — that is the model improvising an interview rather than running this one. Asking the agent directly whether it loaded `grilling` and `domain-modeling` usually recovers it.
+
+## It's working if
+
+- A round arrives as a numbered list, each question with its recommendation on a separate `➡️` line, and you can answer the whole round by number.
+- Nothing in a round needs another question in the same round answered first.
+- Later rounds ask things the first round could not have asked.
+- It goes and looks facts up — reading files, dispatching a sub-agent — rather than asking you something it could have found out.
+- Research running in the background does not stall the round; only the questions that depend on it wait.
+- It stops at the end and asks you to confirm the understanding is shared, instead of starting work.
+- Question count stays high while round count stays low.
 
 ## Where it fits
 
-`grilling` is the interview **primitive** under the main build chain: [grill-with-docs](https://aihero.dev/skills-grill-with-docs) runs it to sharpen context before [to-spec](https://aihero.dev/skills-to-spec) writes the spec. When you're unsure which entry point fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you.
+`grilling` is a **primitive**, not a step you schedule: the single source of truth for the interview technique, kept in one place so every skill that needs an interview reaches for it instead of inventing one. [grill-me](https://aihero.dev/skills-grill-me) and [grill-with-docs](https://aihero.dev/skills-grill-with-docs) are its two user-invoked front doors, and `grill-with-docs` is where the main build chain begins, ahead of [to-spec](https://aihero.dev/skills-to-spec). [wayfinder](https://aihero.dev/skills-wayfinder) runs it to resolve decision tickets, [triage](https://aihero.dev/skills-triage) to grill a vague report into a workable one, and [improve-codebase-architecture](https://aihero.dev/skills-improve-codebase-architecture) to walk the tree once you have picked a candidate to deepen. When you are unsure which entry point fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you.

docs/productivity/teach.md

@@ -1,35 +1,97 @@
 ## What it does
 
-`teach` turns the current directory into a standing teaching workspace and teaches you one topic across many sessions — devising short, beautiful, interactive lessons tied to *why* you want to learn.
+`teach` turns the directory you run it in into a standing teaching workspace and teaches you one topic across many sessions, in short self-contained HTML lessons.
 
-It does **not** teach from the model's own memory. Parametric knowledge is treated as untrusted; before it can teach, it gathers high-trust resources and grounds every claim in a citation. And it is stateful — the workspace remembers what you've learned, so each session picks up where the last left off rather than starting from scratch.
+It does not teach from what the model already knows. Parametric knowledge is treated as untrusted: before it teaches, it goes and finds high-trust resources, records them in `RESOURCES.md`, and cites them inside every lesson. The other structural fact is that it is stateful — the mission, the resources, the lessons and the record of what you have learned all live in the directory as files, so the next session picks up from those files rather than from whatever is left of the last conversation.
 
 ## When to reach for it
 
 You invoke this by typing `/teach` — the agent won't reach for it on its own.
 
-Reach for it when you want to *learn* a topic over time — a language, a framework, yoga, theoretical physics — and want the sessions to accumulate rather than evaporate. It is not for a one-off explanation; if you just need something clarified in the moment, ask directly. Reach for `teach` when the learning is a project.
+Reach for it when the learning is the project: a language, a framework, a codebase you have just joined, yoga, shaders, a certification. It is not the tool for one explanation in passing.
+
+| What you want | What to reach for |
+| --- | --- |
+| To learn a topic over weeks, with sessions that accumulate | `teach` |
+| One idea explained inside the session you are already in | Just ask, in that session |
+| The agent's last message re-pitched because it didn't land | [wait-what](https://aihero.dev/skills-wait-what) |
+| To sharpen thinking you already have, rather than acquire new material | [grill-me](https://aihero.dev/skills-grill-me) |
+| A background agent to read primary sources and leave you a cited document | [research](https://aihero.dev/skills-research) |
+| To learn something that came up mid-grilling, without derailing the grilling | [handoff](https://aihero.dev/skills-handoff) out to a teaching workspace, then `teach` there |
 
 ## Prerequisites
 
-`teach` builds a whole directory in place, so run it somewhere you're happy to keep as a dedicated workspace. Over time it writes:
+`teach` builds a directory rather than producing a file, and the skill assumes one mission per workspace — so run it somewhere you are happy to give over to a single topic. Matt's own guidance, when someone proposed routing the output to a global `~/.learnings/` folder, was to keep it out of the project you are working in: "you can just put them in a separate repo." A dedicated repo also makes the lessons committable, which is how teams have shared them.
 
-- `MISSION.md` — the reason you're learning this, which grounds everything else. If it's empty, `teach`'s first job is to question you until it isn't.
-- `RESOURCES.md` — the vetted, high-trust sources it teaches from.
-- `./lessons/*.html` — the numbered, self-contained lessons (the primary unit of teaching).
-- `./reference/*.html` — compressed cheat-sheets, algorithms, glossaries you'll return to.
-- `./learning-records/*.md` — what you've learned, ADR-style, used to judge what to teach next.
-- `./assets/*` — reusable components (a shared stylesheet first) so the lessons look like one course.
-- `NOTES.md` — your teaching preferences.
+What accumulates in that directory:
 
-## Mission, and the zone of proximal development
+| Path | What it holds |
+| --- | --- |
+| `MISSION.md` | Why you are learning this. Everything else hangs off it; if it is missing, the first thing `teach` does is interview you until it isn't |
+| `RESOURCES.md` | The vetted sources it teaches from, split into Knowledge and Wisdom (communities) |
+| `lessons/*.html` | The numbered lessons — the primary unit of teaching |
+| `reference/*.html` | Compressed cheat-sheets, algorithms, glossaries: the documents you actually return to |
+| `learning-records/*.md` | ADR-style notes on what you have demonstrably learned, used to decide what to teach next |
+| `assets/*` | Reusable components — a shared stylesheet first — so the lessons look like one course |
+| `NOTES.md` | Your stated teaching preferences |
 
-Every lesson hangs off the **mission**. Without it, knowledge has nothing to attach to and lessons feel abstract — so the mission is the first thing `teach` pins down and keeps updating as you grow. From the mission and your learning records it computes your **zone of proximal development**: the next lesson should challenge you *just enough*, no more.
+Two honest notes on that list. A glossary suits most topics, but the skill ships a `GLOSSARY-FORMAT.md` that `SKILL.md` no longer links to, so you will only get one if you ask ([issue #559](https://github.com/mattpocock/skills/issues/559)). And the workspace is not always created where you expect — see the first question below before you build a long course on top of it.
 
 ## Storage strength, not fluency
 
-The word to think with is **storage strength** — long-term retention — as opposed to **fluency**, the in-the-moment recall that feels like mastery but isn't. `teach` deliberately builds the former through desirable difficulty: retrieval practice, spacing, and interleaving. Knowledge is taught first (where difficulty is the enemy), then skills are drilled through a tight feedback loop (where difficulty is the tool).
+The word to think with is **storage strength**: long-term retention, as opposed to **fluency**, the in-the-moment recall that feels like mastery while you are reading and is gone a week later. `teach` builds the former through desirable difficulty — retrieval practice, spacing, interleaving. Knowledge comes first, where difficulty is the enemy because it eats the working memory you need in order to understand; then the skill is drilled through a tight feedback loop, where difficulty is the tool.
+
+Two things steer what you get taught. The **mission** — the concrete real-world reason you want this — grounds every lesson; without it the lessons drift abstract and nothing decides what comes next. From the mission and the learning records, `teach` picks the next lesson inside your **zone of proximal development**: challenging enough to take effort, not so far ahead that it stops being learnable.
+
+It is also why the skill pushes back rather than obliges. A question that needs **wisdom** — real-world judgement — gets an attempted answer and then a pointer to a community where you can test it. A quiz is a gate, not a formality: one user reported saying "thanks a lot" and being told the drill was still live.
+
+## Lessons, references and components
+
+A **lesson** is one self-contained HTML file, short enough to finish in a sitting, tied to the mission, giving one tangible win. It cites its sources, recommends one primary source to go and read yourself, and links to sibling lessons and reference documents.
+
+The split worth knowing: lessons are rarely revisited, reference documents are. So the compressed essence of a lesson — the syntax table, the algorithm, the pose sequence, the glossary — belongs in `reference/`, not buried in the lesson that introduced it.
+
+Lessons are built from **components** in `assets/`: stylesheets, quiz widgets, simulators, diagram helpers. Reuse is the default. The agent reads `assets/` before authoring a lesson and builds from what is there, and anything new that a second lesson could use is written as a component rather than inlined. The shared stylesheet is the first component every workspace earns; it is what stops the output being a pile of one-offs.
+
+## Common questions
+
+**Where does it put the files? Mine ended up in `~/.claude/skills`.**
+A real, open bug ([#377](https://github.com/mattpocock/skills/issues/377)). `SKILL.md` uses `./` for two different roots at once: `./MISSION-FORMAT.md` and its siblings really do sit next to `SKILL.md` in the installed skill, while `./lessons/`, `./reference/`, `./learning-records/` and `./assets/` are meant to be in your directory. An agent that resolves the first kind against the skill's install directory goes on to resolve the second kind there too, and writes your course into the skill folder. Check where the first lesson landed before you build on it, and name the directory explicitly when you start rather than relying on "the current directory" being understood.
+
+**Do I stay in one session, or start a new one per lesson?**
+Asked which of three approaches he uses — stay in the same session, re-invoke `/teach` in a new session, or open a new session in the same folder — Matt's answer was "All three will work." Asked whether each lesson is its own invocation, he confirmed: "Yes, each session." The folder is the continuity, not the conversation. Common practice is to open a fresh session in the workspace and say `/teach next lesson for <topic>`.
+
+**How do I know it isn't teaching me something it made up?**
+You don't, on the skill's word alone. Asked exactly this, Matt's answer was "You read the primary sources" — and asked whether that made `teach` reliable, "Of course not, see my video 'never trust an LLM'." The grounding machinery — `RESOURCES.md`, citations in every lesson, one recommended primary source per lesson — exists to make verification cheap, not to remove the need for it. The failure is not hypothetical: one user learning a 2x2 Rubik's cube was given fabricated move sequences that don't solve it. Matt's diagnostic questions in that thread were "Model, harness, effort? And, what was the source?", which is the right checklist. Risk is highest in procedural domains with precise notation, and lowest where the output is immediately verifiable, like code you can run.
+
+**The correct quiz answer is always the first option.**
+Confirmed by several people, on Sonnet, on Opus and on GLM, and still unfixed. `SKILL.md` now requires every answer to be the same number of words, which kills a different tell — the correct answer used to be the only fully-reasoned one — but says nothing about position. One contributor tested an instruction-level fix for position and reported the correct answer still landing in slot A 33 times out of 33 across nine lessons ([#335](https://github.com/mattpocock/skills/issues/335)), which points at a shuffling quiz component in `assets/` as the real fix rather than better wording. Until that ships, treat answer position as meaningless. Your `assets/` directory is yours to change, so asking for a component that shuffles at render time is a legitimate local fix.
+
+**It assumed I already knew things, and used terms it never defined.**
+The commonest substantive complaint. There is no assessment step: `teach` infers your level from the mission and the learning records, and in session one there are no learning records. One user running it inside a wayfinder pipeline put it plainly — "It never did grilling to establish my starting point so it made lots of assumptions of what I already knew." Another reported lessons leaning on undefined jargon, and a lesson tailored to their hardware that covered what the hardware could do while never saying what it couldn't. Two things help: state your prior knowledge and your gaps in the first message, and correct the level out loud when a lesson misses, because the correction becomes a learning record and steers the next one. An explicit knowledge-assessment step is a standing feature request ([#725](https://github.com/mattpocock/skills/issues/725)), not shipped behaviour.
+
+**Does it do spaced repetition, and does it know when to stop teaching?**
+No to the first, and not reliably to the second. Spacing and interleaving are principles the lessons are designed against, but nothing schedules a review, and there is no Anki or calendar integration — both are recurring requests. The related gap is exit criteria: as one user put it, `teach` "is good at making the next lesson, but not as good at knowing when to stop and switch to review or real practice." If you want review or drilling instead of new material, ask for it; the skill will not propose the switch on its own.
+
+**Is it only useful for code?**
+No, and the non-coding use is the larger part of the record: Korean, Japanese formal register, piano, guitar, board game design, OpenSCAD, film plots, Azure and CCNA certifications, university exams, and children of eight and ten getting printable books on escape rooms and fire salamanders. Nothing in the skill is programming-specific — mission, resources, zone of proximal development and drill work the same way in any domain. Within code, the strongest reported use is not learning a language from scratch but getting oriented in an unfamiliar codebase or a new team's stack.
+
+**Which model should I run it with?**
+There is no canonical answer, and the reported differences are large. Higher reasoning effort has been reported to produce noticeably better lessons than the medium setting. One user ran the same skill through Copilot CLI with Codex and got a single 30-line HTML card where Claude Code produced a full lesson. It runs unmodified in Claude Cowork, subject to whether your organisation allows skills to be added there. If the lessons come out thin, change model, harness or effort before rewriting your prompt.
+
+## It's working if
+
+- The first thing it does in an empty directory is interview you about why you want this, rather than produce a lesson.
+- `RESOURCES.md` fills up before the lessons do, and each lesson names one primary source worth reading yourself.
+- Claims in a lesson carry links out. A lesson with no citations is the skill teaching from memory.
+- A lesson takes one sitting and leaves you able to do one thing you couldn't before.
+- Opening a fresh session in the folder and saying "next lesson" continues the course instead of restarting it.
+- `learning-records/` grows, and lessons stop re-teaching what you have already demonstrated.
+- The lessons look like one course — they link the stylesheet in `assets/` rather than each carrying its own.
+- A question that needs judgement gets you pointed at a forum, subreddit or class, not just an answer.
 
 ## Where it fits
 
-`teach` is a reach-for-it-anytime standalone — a long-running learning project you drive session by session, not a step in a build chain. It shares no workflow with the other productivity skills; it simply owns its workspace directory and lives there. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you.
+`teach` is a **reach-for-it-anytime standalone**. It is not a step in a build chain and shares no artifacts with the engineering flow; it owns its directory and lives there for as long as the topic lasts.
+
+Its one real neighbour is [handoff](https://aihero.dev/skills-handoff), through the composition Matt named as the answer to "what do I do if I'm being grilled about something I don't understand?": don't stop the grilling to learn — `/handoff` to a teaching workspace, learn it there with `/teach`, then go back and pick up where you left off. The nearby alternative is [research](https://aihero.dev/skills-research), for when what you want is a cited document rather than lessons and retention. When you are not sure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you over the whole set.

docs/productivity/to-questionnaire.md

@@ -1,34 +1,78 @@
 ## What it does
 
-`to-questionnaire` turns a decision you can't settle on your own into a **questionnaire** — a Markdown document you hand to the one person who holds what you're missing, to fill in async or work through together in a meeting.
+`to-questionnaire` turns a decision you can't settle on your own into a **questionnaire** — a Markdown document you hand to the one person who holds what you're missing, for them to fill in async or for the two of you to work through in a meeting.
 
-It grills you about the **send**, never the subject. A normal grilling session interrogates the topic, which is exactly what you can't answer here — that's why you're writing to someone else. So the interview asks only the two things you can always answer: who this is going to, and what you need back from them. The questions in the document are then aimed at the **gap** between the two.
+It grills you about the **send**, never the subject. Interviewing you about the topic is pointless here: not knowing the topic is why you're writing to someone else. So it asks the two things you can always answer — who this is going to, and what you need back from them — and aims every question in the document at the **gap** between the two.
 
 ## When to reach for it
 
 You invoke this by typing `/to-questionnaire` — the agent won't reach for it on its own.
 
-Reach for this when a decision is blocked on knowledge that lives in someone else's head — a client, a domain expert, a colleague on another team — and you want a document that pulls it out of them in one pass. When the knowledge is in *your* head and just needs sharpening, use [grill-me](https://aihero.dev/skills-grill-me) instead; when it's in the codebase, use [grill-with-docs](https://aihero.dev/skills-grill-with-docs).
+Reach for it when a decision is blocked on knowledge that lives in one other person's head: a client, a domain expert, an exec who owns the business rules, a colleague on a team you don't sit with. Which skill you want depends on where the answers actually are:
+
+| The answers are in… | Reach for |
+| --- | --- |
+| Your own head, unsharpened | [grill-me](https://aihero.dev/skills-grill-me) |
+| The codebase | [grill-with-docs](https://aihero.dev/skills-grill-with-docs) |
+| Someone else's head | `to-questionnaire` |
+| Nobody's head yet — the question needs something to react to | [prototype](https://aihero.dev/skills-prototype) |
+
+The common case is a grilling session that stalls: some of what surfaced isn't yours to answer. Run `/to-questionnaire` in that same conversation to take those questions offline, then bring the answers back and carry on.
 
 ## The send, not the subject
 
-The interview is two exchanges, and it stops there:
+The interview is two exchanges, and then it stops.
 
-- **Who is it going to?** Their role, expertise, and relationship to you. This fixes the tone and how much context the document has to carry — an outside client needs orienting; a teammate does not.
-- **What do you need back?** The concrete decisions or facts you can't resolve alone. This becomes the checklist the finished questionnaire is measured against: every item you named has a question aimed at it.
+- **Who is it going to?** Their role, their expertise, their relationship to you. This fixes the tone and how much context the document has to carry — an outside client needs orienting, a teammate does not.
+- **What do you need back?** The concrete decisions or facts you can't resolve alone. This becomes the checklist the finished document is measured against: every item you named gets a question aimed at it.
 
-Everything after that is drafting. The output is written to `to-questionnaire-<slug>.md` in the current directory.
+Everything after that is drafting. The file lands at `to-questionnaire-<slug>.md` in the current directory. There is no setup, no workspace, and nothing to configure.
 
 ## The document
 
-It's a **discovery questionnaire**: you lack the context, the recipient holds it. That framing drives its shape — a purpose line and the decision riding on it, a short context section for a recipient who wasn't in your head, and questions ordered **most-important-first**, because async means you may only get one pass. Each question is one idea, never compound, with an answer stub beneath it and a *why this matters* line only where the question could be misread. It closes with a catch-all: anything we didn't ask that we should know?
+It is framed as a **discovery questionnaire** — you lack the context, the recipient holds it — and that framing drives its shape:
+
+- A purpose line naming the decision riding on it, and a short context section for a recipient who was never in your head.
+- Questions ordered **most-important-first** and grouped under themed headings, because async means you may only get one pass.
+- One idea per question, never compound, with an answer stub beneath it and a *why this matters* line only where a question could be misread.
+- Explicit permission to answer "I don't know" — a flagged uncertainty is useful; a confident guess that reads like a fact is not.
+- A closing catch-all: anything we didn't ask that we should know?
+
+Two things it deliberately isn't. It isn't **branching** — the questions are a flat, grouped list, not a tree that skips section D if you answered A. And it isn't **multi-recipient** — one run produces one document for one person.
+
+## Common questions
+
+**Does it read my grilling session and extract the questions from it?**
+Not as a step of its own. The skill has no ingest phase: it asks about the send, then drafts. What makes it work after a grilling session is that you run it in the **same conversation**, so the session is already in context and the drafting can draw on it. Start it in a fresh session and it knows nothing about the grilling — you'll be re-supplying the topic yourself when you answer "what do you need back?".
+
+**The missing answers don't all live with the same person. Can it split them by recipient?**
+No. Step one asks for *the* recipient, singular, and the tone and context of the whole document are pitched at them. If three people hold three parts of the answer, run it three times, once per person. Routing questions by discipline or role inside a single document is a request people have made; it isn't what shipped.
+
+**Are the questions dependent — does it skip sections based on earlier answers?**
+No. The dependent-question design was explored and did not ship. The output is a static document: themed groups, most-important-first, every question live. The objection against it is a fair one — a model planning more than two or three questions ahead of a real answer plans badly, and a branching document has to plan all of them ahead of every answer.
+
+**What if the recipient doesn't know either?**
+The document tells them to say so. "I don't know" and partial answers are asked for explicitly, and a flagged uncertainty is worth more than a guess, because a vague answer and a confidently wrong one look identical once they're back in your context.
+
+**Does it send it anywhere — Slack, an issue tracker, email?**
+No. It writes a Markdown file in the current directory and tells you the path. Delivery is yours: paste it into a ticket, drop it in a Slack thread, attach it to an email, or open it on a shared screen and work through it live. People have wired up all four by hand.
+
+**Isn't this just `/grill-me` in batch mode?**
+No, and the distinction is worth holding. `grill-me` already asks in **rounds** — the whole frontier at once, then recomputed from your answers — so the "give me all the questions at once" need is met there. `to-questionnaire` is about a different axis: not how the questions are delivered, but whose head the answers are in. Answering them yourself faster is `grill-me`; getting them out of someone else is this.
+
+**Couldn't I just ask the agent for this without a skill?**
+Yes, and plenty of people did before it existed — `OPEN_QUESTIONS.md` files, spreadsheets sent to clients, a "needs more info" ticket per unanswered question. The skill buys you two things: the interview never drifts onto the subject, and the document comes out in a shape a non-technical recipient can actually fill in. If you already have a house format that works, the honest answer is that you don't need this.
 
 ## It's working if
 
-- It asks you about the recipient and the deliverable, then stops asking — no interrogation of the topic itself.
+- It asks about the recipient and about what you need back, then stops asking. A question about the subject itself is the skill off the rails.
 - Every item you named as "what I need back" is traceable to a question in the file.
-- The questions read as aimed at what the *recipient* knows, not as your own open questions copied down.
+- The questions read as aimed at what the *recipient* knows, not as your own open questions copied down verbatim.
+- You could hand the file to someone who wasn't in the conversation and they would know why they got it and by when to reply.
+- The answers that come back are usable input for a new grilling round, rather than a fresh set of questions.
 
 ## Where it fits
 
-`to-questionnaire` is a reach-for-it-anytime standalone — it sits at the boundary of your own knowledge, where the next step is another person rather than another skill. Its neighbour is [grill-me](https://aihero.dev/skills-grill-me), because the two split on where the answers live: grilling mines you, a questionnaire mines someone else. What comes back typically feeds the main flow at [grill-with-docs](https://aihero.dev/skills-grill-with-docs) or [to-spec](https://aihero.dev/skills-to-spec). When you're unsure which skill fits the moment, [ask-matt](https://aihero.dev/skills-ask-matt) routes you.
+`to-questionnaire` is a reach-for-it-anytime standalone. It sits at the boundary of your own knowledge, where the next move is another person rather than another skill — most often mid-flow, when planning has stalled on something that isn't yours to decide.
+
+Its neighbour is [grill-me](https://aihero.dev/skills-grill-me), and the two split on where the answers live: grilling mines you, a questionnaire mines someone else. What comes back is raw material — feed it into another grilling round, or into [grill-with-docs](https://aihero.dev/skills-grill-with-docs) or [to-spec](https://aihero.dev/skills-to-spec) if the work is heading for a build. When you're unsure which skill fits the moment, [ask-matt](https://aihero.dev/skills-ask-matt) routes you.