Every decision the AI surfaces to the human is a clickable question with concrete options —
not a wall of prose ending in a question mark.
The human's job is to decide, not to re-read explanations.
Free-text questions silently degrade to rubber-stamping
Buried in prose, the human must scan, extract, and reformulate the question before they can decide.
Free-text replies drift, lose context, and force follow-up clarifications. Clickable options collapse the round-trip.
Each option exposes its cost, risk, and reversibility — the human decides on signal, not memory.
Mechanical, not aesthetic
Whenever the AI needs a decision, preference, or
disambiguation from the human, it MUST use the
AskUserQuestion tool with
2–4 concrete, mutually exclusive, clickable options.
Free-text questions buried in prose are forbidden — including for non-gate matters such as scope clarification, mode disambiguation, library/approach choice, naming, refactor depth, or “should I continue?” checkpoints.
? — that is a violation.
Rewrite as an AskUserQuestion call.
Five fields — each one carrying a piece of the decision
question
The actual decision, phrased as a single sentence. Short. No nested questions.
header
A 1–3 word category label shown above the question. Helps when bundling related decisions.
options[].label
Each option label is ≤ 5 words, decision-shaped, mutually exclusive. The recommended option goes first and is suffixed with (Recommended).
options[].description
Carries the why — cost, risk, reversibility. So the human can decide without scrolling back to read prose.
multiSelect
false by default (one choice). Set true only when several options can co-exist.
A single decision with a clear recommendation
Which database should the auth service use?
Robust, supports JSONB & row-level locks. Higher ops cost — we already run one in prod.
Zero ops. Single-writer limit blocks horizontal scale — reversible only behind a migration.
Managed & cheap at low volume. Locks us into AWS; query patterns are pre-committed.
So I’ve been looking at the storage layer and I think we have a few options on the table. Postgres is probably the most robust choice and we already operate one in production, although it does add some ops cost. SQLite would be much simpler to deploy as a single file but has single-writer limitations which would bite us once we scale horizontally. DynamoDB is also worth considering since it’s managed and cheap at low volume but it would lock us into AWS and force us to commit to query patterns up front.
So — should I go with Postgres, SQLite, or DynamoDB? Or did you have something else in mind?
The human has to scan three paragraphs, mentally extract the trade-offs, type a reply, then often re-clarify.
Up to 4 related questions in one call — never split across turns
How deep should the auth refactor go?
Minimal blast radius, ships behind feature flag. Still leaves session storage as next sprint’s problem.
Closes compliance gap fully. Bigger PR, requires migration plan.
Behind a feature flag?
Reversible without deploy. Adds one branch point in code.
Cleaner code. Rollback requires revert + deploy.
Migration window for existing sessions?
No forced re-login. Two code paths active during the window.
Clean cutover. User-visible disruption.
G1 / G2 / G3 are decisions too — the evidence block carries the why, AskUserQuestion carries the verdict
Approve plan EXP-014-auth-refactor for production?
Evidence: prototype confirmed · insights.md written · Challenger output recorded · Kill Criteria defined.
All gate criteria satisfied; gatekeeper-g2 verdict: PASS.
Signal a missing artefact or a flaw in the approach — no production code starts.
Park the plan as PROP-NNN for later triage; no scope is lost.
What to never do — and what to do instead
| Anti-Pattern | Why it fails | Better |
|---|---|---|
Free-text trade-off prose ending in ? |
Forces re-reading; ambiguous to answer. | AskUserQuestion with 2–4 options & trade-offs in description. |
| Single-option Confirm → Yes/No | Theatre, not decision — one side is meaningless. | Just proceed and report. Or pose a real either/or. |
| Splitting one decision across 3 consecutive turns | Adds latency, loses context. | One AskUserQuestion call with multiple questions. |
| Tool call followed by free-text question | Re-introduces the prose-question pattern. | Bundle into the same call, or wait for the answer. |
| Manual “Other / Custom” filler option | The tool already injects an “Other” fallback. | Drop it — rely on the built-in fallback. |
When the rule applies — and when it doesn’t
/promote vs. /defer vs. /rejectHow AskUserQuestion fits into the framework’s rule system
Clickable options are the mechanical form of “human decides”.
The AI must still recommend; the human still chooses.
For gate transitions: the tool carries the decision, the evidence: block carries the justification. Both required.
The canonical, machine-readable rule lives next to the rest of the framework.
guidelines/ask-user-question.md
open_in_new