--- name: to-questionnaire description: Turn a decision you cannot make alone into a Markdown questionnaire for the person who can. disable-model-invocation: true --- # To Questionnaire Turn something you cannot answer alone into a **questionnaire**: a Markdown document handed to one person, filled in async or worked through together in a meeting. They hold knowledge you lack, and the questionnaire pulls it out of them. **Grill the send, not the subject.** This is the inverse of a grilling session. Do not interview the user about the topic, because the whole premise is that they cannot answer it. Interview them about the **send**, which they can always answer: who it is going to, and what they need back. The questions in the document then target the **gap** between what the recipient knows and what the user needs. Two exchanges, then write. ## 1. Who is it going to? Ask, in one exchange, the recipient's role, their expertise, and their relationship to the user. This fixes the tone and how much context the document must carry. Tone follows the recipient: | Recipient | Pitch | |---|---| | A technical project manager (Conrad) | Technical is welcome and preferred. Do not water down schema, API, or data-model questions into vague business phrasing. Write it as something a person wrote, not as generated filler. | | A tech lead (Henry) | Assume full technical fluency. Lead with the constraint or risk being decided, and name the trade-off explicitly. | | A client or non-technical stakeholder | Domain language only. Every technical consequence stated as an outcome they would feel, never as an implementation detail. | **Done when** you know who the recipient is and what they know that the user does not. ## 2. What do you need back? Ask, in one exchange, the specific decisions or facts the user cannot resolve alone and needs from this person. **Done when** you have a concrete list of what the user must walk away able to do or decide. Not "understand the requirements": *"know whether partial refunds are in scope for phase one."* ## 3. Write it Draft questions aimed at the gap, following the structure below. Write to `to-questionnaire-.md` in the current directory, or into `.claude/docs/epics//` where the question belongs to a Jira story and that directory already exists. Report the path. **Done when** the file exists and every item named in step 2 is covered by a question. ## Document structure Frame it as a **discovery questionnaire**: the user lacks context, the recipient holds it. Order questions **most important first**, because async usually means one pass and later questions get thinner answers. Group them under `##` headings by theme once there are more than a handful. # **Purpose:** why this exists and the decision riding on it. **From:** , **To:** , **How your answers will be used:** ## Context One paragraph orienting a recipient who was not in the user's head. Enough to answer well, not a page. ## How to answer The deadline and the rough effort. Partial answers and "I don't know" are useful: flag anything uncertain rather than skipping it. ## One `##` section per theme, its questions most important first. Every question is one idea, never compound, with an answer stub directly beneath it, and a one-line *why this matters* only where the question could be misread or would otherwise invite a throwaway answer. ### What load is the system expected to handle at launch? _Why this matters: it decides whether we provision for burst traffic now or defer it._ > ## Anything else? A closing catch-all: anything we did not ask that we should know? ## Done when - The user was interviewed about the send, never about the subject. - Every question is one idea with an answer stub, ordered most important first. - Tone and technical depth match the named recipient. - Every fact or decision from step 2 is covered by a question, and the file's path was reported.