# 1 · The brief Most re-prompts happen because you started building before you knew what the human meant. The human holds context they didn't type: who it's for, what they've tried, what they'll judge it on. You fill the gaps with averages. The fix is not to ask more questions. It's to ask the **right** ones, once, and to state your assumptions for everything else. --- ## Step 1 · Gather before you ask Before asking anything, look for answers in: 1. The request itself, including what it implies but doesn't say. 2. `DESIGN.md`, README, existing screens, the theme or token files. 3. The tech already in use (framework, CSS approach, component library). 4. Real content: actual product names, data shapes, copy that already exists. **Agent trap:** asking the human something the codebase already answers. That costs them a round trip and signals you didn't look. --- ## Step 2 · Fill in the brief Answer each line. Mark each answer **known** (stated or found) or **assumed** (your inference). | # | Question | Why it changes the design | Sensible default if unknown | |---|----------|---------------------------|-----------------------------| | 1 | **Who** uses this, and in what situation? (device, rush, expertise, frequency) | A nurse on a phone between patients needs different density than an analyst at a desk. | Mixed devices, moderately experienced, a bit rushed. | | 2 | What is the **one job** of this screen? | Decides the primary action and the hierarchy. | The most frequent action mentioned in the request. | | 3 | What does **done** look like? | Stops you from over- or under-building. | One working screen, all states, responsive, accessible. | | 4 | Is there an **existing system** or brand? | Using it beats inventing one, every time. | Search the codebase. If none, create a minimal token set. | | 5 | **Constraints**: tech, accessibility level, languages, performance? | Rules out whole approaches. | Existing stack; WCAG 2.2 AA; English but allow 30% text growth. | | 6 | What is the **real content**? | Placeholder content hides layout bugs. | Realistic content including long, empty and extreme values. | | 7 | How should it **feel**? | Taste words need translating (`4-taste.md`). | Calm, clear, unbranded-neutral. | --- ## Step 3 · Decide whether to ask Ask **only** when all three are true: - you can't infer the answer from step 1, - a wrong guess would mean redoing significant work, and - the human is available to answer. When you do ask: - **At most 3 questions, in one message.** Never drip-feed questions. - **Each question carries your default.** "Who's this for? I'll assume small-team admins on desktop unless you say otherwise." - **Make them answerable in a word.** Offer options when you can. If the human is not available (a background task, an automated run), don't ask. Proceed on your defaults and list them clearly in the report. **Agent trap:** asking permission for things that are cheap to change later (a colour, a label). Decide those yourself and mention them. --- ## Step 3b · Pattern choices: ask, don't pick *Added in v0.2 after a designer's review. The agent confirmed a sent invite with a toast. The designer said a centred confirmation dialog with next steps was just as valid, and that the agent should have asked which one they wanted.* Some decisions have **more than one correct answer**. Both options follow good UX, and the right one depends on the product, its users and the human's taste. These are not yours to decide silently. **Rule:** When you reach one of these forks, and the human hasn't decided it already (check `DESIGN.md`): 1. **Ask once, with the options side by side.** Say what each feels like to the end user and when each fits better. 2. **Recommend one,** with a one-line reason, so the human can answer "yes". 3. **Batch the forks.** Collect every fork you can see during the brief and ask about them together, within the 3-question limit. 4. **Record the answer in `DESIGN.md`** as a project pattern, so neither you nor the next agent asks again. The answer applies everywhere that fork appears in the product, not just here. 5. **If the human isn't available:** pick your recommendation, build it so it's easy to switch, and list the fork under "Assumed" in your report. ### Common forks | Fork | Option A | Option B | A fits when… | B fits when… | |---|---|---|---|---| | Confirming a completed action | **Toast** (corner, auto-dismiss, Undo) | **Dialog** (centred, "Done. Here's what happens next", OK button) | The result is visible on the page and the action is routine | The person must know the next steps, or the action is rare and important | | Protecting a destructive action | **Undo** after acting | **Confirm** before acting | It can be reversed | It can't be undone (deleting data, sending money) | | Saving settings | **Autosave** each change | **Save button** per form | Changes are small and safe | Changes are related, risky, or cost money | | Moving between sections | **Tabs / sidebar** on one page | **Separate pages** | Sections are short and related | Sections are long or unrelated | | Long forms | **One page** | **Steps** (wizard) | Under about 7 fields, or experts | Many fields, first-time users, or later steps depend on earlier ones | | Showing extra help | **Inline** (always visible) | **Disclosure** (accordion, popover) | Most people need it | Only some people need it | | Error placement | **Next to each field** | **Summary at the top** + next to each field | Short forms | Long forms where the first error may be off-screen | **Why:** A silent choice on a fork is a coin flip from the human's point of view. When it lands on the other side, they re-prompt, and they feel the agent didn't listen. A 10-second question with a recommendation is cheaper than a redo, and the answer, once recorded, serves the whole product. **Agent trap:** treating the option you picked as "the best practice" because it's common. Common isn't the same as right for this product. Toasts, for example, are common, but they're easy to miss, and a centred dialog may be exactly what a first-time admin needs. --- ## Step 4 · Write the brief back Before building, write the brief in five lines. This is where the human catches a misunderstanding before it costs anything. ``` Building: for , used . One job: . Feel: → . System: . Assumed: . ``` --- ## Check - [ ] Every brief line is marked known or assumed. - [ ] You asked 0–3 questions, all in one message, each with a default. - [ ] Every pattern fork you met was asked (with a recommendation) or listed under "Assumed". - [ ] Every answered fork is recorded in `DESIGN.md`. - [ ] Your final report repeats the "Assumed" line.