AI states
Design the moments an AI feature has besides the one where it works.
Teams design the demo: the user asks, the AI answers, everyone claps. Then real people use it. They ask something it cannot do, it takes fourteen seconds, it answers with total confidence and is wrong, the connection drops mid-sentence, and the product shows a spinner and "Something went wrong". Now that the AI also acts - it sends, books, edits and keeps working while nobody watches - the undesigned moments are worse: it did something, and the user cannot tell what.
So the job is not "design the chat". It is: at every moment, the user knows what the AI is doing, what it is based on, and what they can do next - and, when it acts for them, what it did and how to take it back.
The aim is calibrated trust: users rely on the feature as much as it deserves, case by case. Both ways of missing are failures - accepting without looking, and redoing everything by hand.
What every AI feature must get right
Check these first. They are what a user notices when they are missing.
- Never a bare spinner. After about two seconds the user needs to know what is happening, and after ten, how to stop it or leave.
- Four different "no"s. Doesn't know (no information), can't (not something it does), won't (not allowed) and broke (system failure) have different causes and different next steps. One generic error for all four makes users retry things that will never work.
- Not knowing is a designed state, not an error. "I couldn't find that in your documents" is a good answer. It is what makes the other answers believable.
- Nothing looks complete when it is not. A partial result that looks whole is the most dangerous state there is, because nobody checks it.
- Limits are said up front. The user learns what it can and cannot do from the first screen, not from failing.
- Every dead end has a way out, and nothing the user gave it is lost: what they typed, attached or selected, and the previous result, are still there after any failure.
- Checking costs less than redoing. Answers show what they stand on, in proportion to the stakes - the source next to the claim, the pages covered, the date it is current to. If verifying means doing the work again, the feature saves nothing.
- Before it acts, it shows; after it acts, it can be undone. Anything that sends, deletes, pays or changes something gets a preview, and a confirmation when it cannot be reversed. Confirm what matters, not everything: constant prompts train people to approve without reading.
- Work done unattended comes back as a report, not a cheer: what was done, what was not, what was not verified, and where to look first.
- It says only what the system can know. No confidence label the model cannot back, no "I checked" when nothing was checked, no "I'll remember" when nothing is stored.
How to work
-
Understand the feature before drawing anything. You need: what the AI does and for whom; the surface (read
references/surfaces.md, including whether chat is the right one); what it reads and what it can change; what the system can actually detect and expose - streaming, sources, a refusal signal, a retrieval score, error types, step events; whether a human fallback exists; language and register. Read what the user gave you, then ask for what is missing in one round. If you cannot ask (a non-interactive run, or the user is away), assume the most likely answer, mark every trigger that depends on it to confirm, and list the assumptions. Do not invent capabilities: a state the system cannot detect cannot be built. That is different from a signal the team has to build: if a state the feature needs depends on something the system does not expose yet (an error type, a refusal flag), design the state and list the signal as to build in the signals table - that table is often the most useful thing engineering gets from you. -
Set the stakes. They decide how much each state needs.
Stakes Examples What changes Low brainstorming, rewriting a sentence, casual questions Light touch: regenerate and edit are the safety net Medium summaries people act on, answers about the user's own account or company data Sources, visible scope, a clear "not found" High money, health, legal, security, anything sent to others or irreversible Confirmation before acting, evidence in the path, a human route, an audit trail Stakes come from what people do with the output, not from whether the AI acts: a read-only summary of a contract that lawyers rely on is high stakes. For a high-stakes feature that takes no actions, "high" means evidence in the path, visible coverage and a human route - there is nothing to confirm.
-
Go through the ways it fails (
references/failure-modes.md). Most are silent: a fluent wrong answer, an omission, an agent doing more than asked, an instruction planted in a document. For each one that can happen here, name the state or pattern that defends against it. -
Build the state map. Go through every state in
references/states.mdand mark it:- Applies - yes, no (with the reason), or only if a signal exists that you could not confirm.
- Today (when reviewing something that exists) - designed, incomplete (it exists but lacks something the stakes require - say what), generic (a catch-all handles it) or missing.
An only if state gets a spec block and a row in the map, counts as "to confirm" in the coverage strip rather than in the total, and gets a card only when it is likely enough to be worth drawing.
If the AI runs several steps, uses tools on its own or works while the user is away, do the same with the delegation states in
references/delegation.md, and fill in the autonomy level and the permission table for each kind of action. A chat that takes one action after the user confirms it is not an agent: state 5 (with its "after confirming" screen and the undo) covers it, plus a three-column permission table. Do not force D1-D12 onto it. Do not skip the map even when the user asked about a single state: tell them which others the feature needs. -
Specify each state that applies in the format below.
-
Draw the board. Start from
assets/template.html: one card per state, showing the real component in that state with the final copy. A list of states in prose gets nodded at; a board where the gaps are visibly missing gets fixed. Use the product's own look if you were given it (colours, components, screenshots); otherwise keep the template's neutral style and say so. Draw the feature's real surface: a button-and-panel feature gets panels, not chat bubbles. A state that needs several screens (before and after confirming) stays one card with those screens. For a new design, delete the template's findings block and the map's Today column, and let the coverage line say how many states apply, how many do not, and how many wait on a signal. -
Write the copy following
references/copy.md, in the language and register of the product. -
Write the test script and the measures (
references/measure.md): one input that provokes each state, and what to log for it. -
Review against
references/checklist.mdandreferences/anti-patterns.md, looking at the rendered board, not the source.python scripts/screenshot.py board.html board.pngrenders it to an image you can open (in-app browsers often refuse local files); add--tile 1400to get it in readable slices when the board is long. If you change the board after looking, render again. -
Deliver the board, the spec, and a short list of what you assumed and what you need answered. Say what you verified and what you did not.
What to read. Always: states.md, copy.md, checklist.md, and the section of surfaces.md for this surface. For a review, also failure-modes.md and anti-patterns.md. Only for agents (several steps, tools, unattended work): delegation.md. measure.md when you write the test script.
The states
Fourteen answer states in five moments. Each is detailed in references/states.md with what the user needs, the pattern, the anti-pattern and copy.
| Moment | State | The user is asking |
|---|---|---|
| Before | 1. First use | What is this and what can I ask? |
| 2. Composing | What will it use? Is my input fine? | |
| During | 3. Working | Is it doing something? How long? Can I stop it? |
| 4. Needs a clarification | What does it need from me? | |
| 5. Needs my go-ahead | What exactly is it about to do? | |
| Answer | 6. Answer | What is this based on? What can I do with it? |
| 7. Partial answer | Which part is done and which is not? | |
| 8. Unsure | How much should I rely on this? | |
| No | 9. Doesn't know | Is there no answer, or did it not look in the right place? |
| 10. Can't do that | Who or what can? | |
| 11. Won't do that | Is it me, or the rule? What can I ask instead? | |
| 12. Broke | Did I lose my work? Do I try again? | |
| After | 13. Corrected | Did it take my correction? Will it happen again? |
| 14. Handed to a person | Who has it now, what do they know, and when? |
Twelve delegation states, for AI that acts. Detailed in references/delegation.md.
| State | The user is asking |
|---|---|
| D1. Brief | Did it understand the job, and its limits? |
| D2. Plan | How is it going to do it, and can I change that? |
| D3. Permission | What exactly am I letting it touch, and for how long? |
| D4. Working unattended | Is it still on track? Do I need to watch? |
| D5. Needs you | What is it waiting for, and what happens if I don't answer? |
| D6. Steered | Did it take the new instruction? |
| D7. Handback | What did it do, what did it not do, and where do I look first? |
| D8. Review at scale | Which of these 140 changes do I actually have to look at? |
| D9. Undo and repair | Can I take it back - all of it, or just this? |
| D10. Went wrong while away | How bad is it, and where did it stop? |
| D11. Learns | What does it now assume about me? |
| D12. Acts toward others | What do other people see - and do they know it was the AI? |
For an agent that works in the background with no conversation, several answer states are replaced by their delegation counterpart rather than drawn twice: Composing by D1 Brief, Working by D4, Needs a clarification by D5. Mark the answer state "no - see D4" in the map. A recurring job (every night, every Monday) has a standing brief and plan: D1 and D2 are the settings the user reviews once and can see before each run. On such a board you may order the cards by time (before, while it works, when it hands back) instead of by the five moments, if that reads better; keep the state numbers.
An action the product itself rejects for a business reason (not enough balance, a date already taken) is none of the four "no"s about the AI: show it as a screen of state 5, with the reason from the system and what the user can change.
Four things cut across all of them and go on the board as notes: interruption, memory, proactivity (the AI speaks first) and cost (credits, quotas, spend). See the end of references/states.md.
If you can only design five: Working, Doesn't know, Broke, Partial answer, and Needs my go-ahead when it acts (Handback when it works unattended). Those are where trust is lost fastest.
Spec format
One block per state, in this order. Developers build from the trigger; without it the state is a wish.
### 9. Doesn't know
- **Trigger:** retrieval returns no passage above the threshold. (to confirm: the threshold value)
- **Shows:** the answer bubble, neutral style (not the error style).
- **Copy:** "No encontré información sobre licencias por mudanza en las políticas de RR. HH."
- **Actions:** Reformular · Ver las políticas · Preguntarle a RR. HH.
- **Keeps:** the question, editable.
- **Goes to:** 2 Composing, or 14 Handed to a person.
- **Test:** "¿Hay licencia por mudanza?"
- **Measure:** `answer_not_found` with the query; watch the rate by topic.
- **Open question:** can the system tell "no documents" from "documents exist but the user has no access"?
Translate the labels (Trigger, Shows, Copy...) when the team works in another language: Disparador, Muestra, Texto, Acciones, Conserva, Lleva a, Prueba, Medición, Pregunta abierta.
Keeps is whatever the user would lose: typed text, attachments, the selection, the previous result, the work an agent had already done.
Language and register
Write in the language the user asks for; if they do not say, use the language of their request and of the product. Register is the product's choice, not a default: find out how the product already talks (usted, vos, tú; formal or warm) and keep it in every state. The error state is where teams slip into another voice - a formal "Ha ocurrido un error" inside a product that says "¡Listo!" everywhere else reads as a different company.
Two languages can be in play. The copy - everything inside the drawn screens - is in the product's language and register. The board and spec around it - state names, headings, the spec's labels, your notes - are in the language the team works in, which is the language the user wrote to you in. Do not leave the template's English headings on a board for a Spanish-speaking team. The examples in the reference files are in formal Spanish and English; they show the pattern, so rewrite them in the product's register rather than copying them.
The AI's own voice: if the product has the AI speak in first person, keep the "I" for what it did ("No encontré...", "Usé los tres archivos"), not for feelings it does not have ("Me encantaría ayudarte"). If the feature has no persona - a button, a panel - write in the product's impersonal voice ("No se pudo leer el archivo"). One short apology at most, only when the system failed. See references/copy.md.
Reviewing an existing feature
When the user shares an AI feature that already exists (screens, a prototype, a description):
- Build the state map with both columns: Applies and Today. If you have not seen the product, say that "today" comes from the user's description.
- Order the gaps by harm using the severity rubric in
references/failure-modes.md: how bad, how often, and above all whether the user can tell it happened. Silent failures come first - an empty summary that looks like a summary outranks an ugly spinner. - Deliver the map, the ordered findings, and the designed fix - board cards with final copy, not advice - for every critical and major gap, and at least the three worst. Minor gaps can stay as a line in the findings.
Output
Unless asked otherwise:
- The state board - one HTML page from
assets/template.html: the coverage strip, the findings when it is a review, a card for every state you designed, the cross-cutting notes, the map, and the signals the system must expose. Final copy in place, ready to share or screenshot. - The spec - Markdown: what the system is known to do and what you assumed, the state map, one block per state, the permission table when it acts, the signals table, the test script, open questions.
- In your message - the stakes you assumed, the assumptions that most change the design, and the questions you need answered. Keep the full list in the spec.
No placeholder copy on the board. "Error message here" is the state not being designed. A realistic example value - a person's name, a ticket number, the name of a section - is not a placeholder: use it, and list it as an example in the spec so nobody ships it as fact.