Gabriel Brown
89761a7da3
Agent instructions, skills, SSH host aliases and expansion triggers are worth having identical on every machine one person owns, and belong in none of the shared configuration. They live in user/ now, with a manifest saying where each piece goes and a link-user stage that puts it there. That stage does nothing unless the machine said yes. Somebody who clones Panama to try the desktop keeps their own ~/.claude/CLAUDE.md exactly where it was; the question names the destinations and defaults to no. Anything displaced goes to config/old rather than being deleted. ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md were byte-identical copies of one file, which is the drift this exists to prevent. Also adds the vitals toggles for the battery and Claude usage readouts, which had preferences and no way to reach them.
103 lines
4.0 KiB
Markdown
103 lines
4.0 KiB
Markdown
---
|
|
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.
|