Decision Question
Ask only when a real user decision is required. When asking, present the smallest complete decision brief that lets the user choose deliberately.
Questions spend user attention. Spend it only on decisions the user owns, and make each question decision-complete. This skill owns how to ask. It does not own whether a mutation is authorized or whether a task is finished.
voice.md routes here and does not carry the protocol. Load the reference and
script only when the routing gate says ask.
Triggers
ask the user to choose between these paths, do I need a user decision here,
present a decision brief, which option should the user pick
Routing gate: when NOT to ask
Multiple implementation choices do not make a user decision. Do not ask when any of these holds:
- the user delegated the choice (
choose the best option and implement it); - repository or safety policy mandates one option;
- existing acceptance criteria already determine the choice;
- the distinction is an implementation detail within authorized scope, and reversible;
- reading available evidence or tools resolves the uncertainty;
- the task is terminal under the task-completion contract and the question would only solicit optional follow-up. The STOP TOKEN wins.
no unresolved user decision -> act within existing authorization
material unresolved user decision -> build the brief below
Process
All commands run ${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/decision-question/scripts/decision_question.py
with python3. Output is one JSON object.
Route. Apply the gate. If no question is warranted, act and stop.
Draft the brief for the earliest load-bearing decision (fields below).
Check and plan. Write the brief as JSON and run:
python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/decision-question/scripts/decision_question.py" --brief <brief.json>status: incomplete(exit 2) lists the missing fields. Enrich the brief and rerun.status: revise_recommendation(exit 2) means an earlier answer filtered out the recommended option: pick a remaining option or setno_recommendation, then rerun.status: asklists the promptpagesand thepageto present now.Ask, then prune. Present the decision with
AskUserQuestion. Record the answer underanswersand rerun. When the user picks_more, add one to that decision's count underpagingand rerun; the same decision returns its next page. Decisions that depend on an answer are pruned or filtered from that answer, and unresolved IDs are never renumbered.Weak evidence on an irreversible choice.
pre_ask_reviewin the output namesdecision-criticandpre-mortem. Run one before asking.
Scripts
decision_question.py
python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/decision-question/scripts/decision_question.py" --brief <brief.json> [--max-options N]
Reads one decision, or {context, decisions, answers, paging}. Routes, then validates
and plans the next actionable decision. --max-options overrides the pinned
per-prompt bound for a harness that reports a different cap (minimum 3).
Exit codes:
0: routing resolved. No question warranted (skip), a complete bounded brief (ask), every open decision held (held), or nothing left (resolved).1: unreadable or malformed brief JSON, an answer that is not one of the decision's options, a duplicate decision ID, an out-of-rangepagingcount, or a cap below 3.2: a question is warranted but the brief is not decision-complete (incomplete, with the missing fields listed), or an earlier answer removed the recommended option (revise_recommendation).
Decision brief contract
Each decision carries a stable ID (D1, D2), a one-sentence statement of what
must be decided now, why it matters now, at least two materially distinct options
(presented 2 to 4 per page; overflow becomes a split chain) with their consequences, a recommendation with its load-bearing reason (or an
explicit statement that evidence supports none), and Hold only when deferring
is legitimate and a reopen condition exists. Render with the harness
AskUserQuestion tool (voice.md defines the term); do not invent a new UI
contract.
Field rules, option construction, split chains, Hold, and the completeness check: decision-brief-protocol.md.
Five or more options
Never drop an option. Pick one shape:
- Batch coherent alternatives into groups of at most 4.
- Split into one call per option, each answered Include, Defer, Cut, or Hold. This is the default when unsure. A Hold answer stops the chain at once. Check dependencies before you fire the chain.
More than 6 options: first ask a meta-question (proceed, narrow, or batch).
Write non-ASCII text (CJK, accents) as literal UTF-8. Never \u-escape it.
Harness bound
decision_question.py pins what the Claude Code AskUserQuestion schema accepts:
1 to 4 questions per call, 2 to 4 options per question, and a free-text Other
the tool adds itself. Hold and the continuation entry each take a presented
slot. Options beyond the bound split into ordered pages. Another harness with a
different cap: pass the observed value as --max-options.
Relationship to existing capabilities
decision-rigor(areviewreference) stays a PR review axis. This skill reuses its concepts (assumptions, distinct alternatives, reversibility, failure modes) and none of its verdict schema,CONTEXT_MODE, or JSON output.decision-criticandpre-mortemare optional steps for high-impact decisions, not steps for every question.
Anti-Patterns
| Avoid | Why | Instead |
|---|---|---|
| Asking when the user delegated the choice | Spends attention the user already gave away | Act within authorization |
| More options than the harness shows | The user cannot see or pick the overflow | Split into a deterministic chain |
| Asking D2 before D1 is answered | D1's answer may make D2 moot | Ask D1, then prune D2 |
Hold with no reopen condition |
The decision silently disappears | State the event that reopens it |
| Omitting a recommendation the evidence supports | Pushes the cost back to the user | Recommend and give the reason |
| Fabricating a recommendation | Invents confidence the evidence lacks | Say evidence supports no preference |
Verification
- The routing gate ran. A delegated, policy-mandated, criteria-determined,
detail-level, evidence-resolvable, or terminal case emitted no question
(
status: skip, exit 0). - The presented decision is complete (
status: ask, exit 0). - No page exceeds the bound; over-bound briefs report
split: true. - Dependent decisions were pruned or filtered from the recorded answers.
- A held decision keeps its ID and states its reopen condition.