---
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-<slug>.md` in the current directory, or into `.claude/docs/epics/<KEY>/` 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.

<questionnaire-template>

# <Questionnaire title>

**Purpose:** why this exists and the decision riding on it.

**From:** <the user>, **To:** <the recipient>, **How your answers will be used:** <where they go>

## 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.

## <Theme heading>

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.

<question-example>
### 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._

>
</question-example>

## Anything else?

A closing catch-all: anything we did not ask that we should know?

</questionnaire-template>

## 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.
