Clarifying Questions
Ask in options, not in paragraphs
An agent that needs a decision either guesses or asks in prose — four numbered questions the user answers in one paragraph that quietly leaves one out. Clarifying Questions gives every open decision its own card: two to four options, each with its consequence in one line, one marked as the recommendation, a free-text escape, and a skip that hands the call back to the agent on a stated default. Unlike Disambiguation Branch, which offers competing readings of the whole request, these are independent decisions the request left open; unlike Approval Gates, which asks yes or no on an action already chosen, they ask which action — mid-run, once the agent has read enough to know what is open.
Framing
The problem
An agent that needs a decision either guesses silently or asks in prose, and the user answers four numbered questions in one paragraph that leaves one out — which the agent then fills with a guess.
The pattern
Give every open decision its own card with two to four consequence-labelled options, a recommended default, a free-text escape and a skip.
Why chat breaks here
Chat asks in paragraphs and receives paragraphs, so the answer has to be parsed back into decisions — and a question the user forgot looks exactly like one they chose not to answer.
Risks
Asking what the agent could have inferred turns clarification into a form to fill in, and a recommendation that is always accepted becomes a rubber stamp.
Avoid when
Running and redoing is cheaper than answering, or the open decision is one the user has no opinion on.
Use when
An agent reaches decisions it cannot infer, and a wrong guess costs a rerun or a revert.
DOPE evaluation
- Directability
- Each decision is answered on its own card — pick an option, write your own, or skip — instead of inside one reply paragraph
- Observability
- A stepper shows how many decisions are open and which are answered: 2 of 4, not a wall of numbered prose
- Predictability
- Every question names its recommended default, so a skip is a known outcome rather than a silent guess
- Explainability
- Each option carries its trade-off in one line, so the choice is made against its consequence, not its label
In the wild
- Claude Code AskUserQuestion (Anthropic) — The agent asks through a tool, not in prose: multiple-choice questions when it needs a decision, answered by picking an option or typing into an Other row. The documented detail closest to a Skip is an opt-in auto-continue timeout: an unanswered question closes, submits whatever was already selected, and tells Claude you may be away, so it proceeds on its own judgment and can re-ask later. The fallback is Claude’s judgment, not a default named in advance.
- OpenAI Codex (OpenAI) — Captured Sep 2026: asked for decisions it could not infer, Codex docks a Question tray above the composer — “1 of 3” with arrows, numbered options that each carry their consequence, a free-text “Or write your own response”, Skip and Next. The same card shape as Claude Code; the questions also stay in the transcript as plain lines.
- Cursor 2.1 Clarifying Questions (Cursor) — Nov 2025: Plan Mode asks multi-question clarification with pickable answers before it writes the editable Markdown plan. Moved here from Disambiguation Branch — it asks independent questions, it does not offer competing readings.
FAQ
When should I use the Clarifying Questions pattern?
An agent reaches decisions it cannot infer, and a wrong guess costs a rerun or a revert.
When should I avoid the Clarifying Questions pattern?
Running and redoing is cheaper than answering, or the open decision is one the user has no opinion on.
What problem does Clarifying Questions solve?
An agent that needs a decision either guesses silently or asks in prose, and the user answers four numbered questions in one paragraph that leaves one out — which the agent then fills with a guess.
Why is chat the wrong fit for this?
Chat asks in paragraphs and receives paragraphs, so the answer has to be parsed back into decisions — and a question the user forgot looks exactly like one they chose not to answer.