ask-user-question

name	ask-user-question
description	Use ask_user_question for structured user decisions: ambiguous requirements, meaningful design preferences, high-impact trade-offs, or preview-based choices. Avoid plan approval and generic proceed confirmations.
metadata	{"short-description":"Structured user decision prompts"}

Ask User Question Decision Skill

Use this skill when a task reaches a decision boundary where the user's preference or explicit choice matters.

This skill is about decision gathering, not permission prompts.

Use ask_user_question when

Use the tool when any of these are true:

1. A meaningful implementation/design choice has multiple valid answers.
2. Requirements are ambiguous, conflicting, or underspecified.
3. The choice affects architecture, schema, API contracts, deployment, security, or irreversible work.
4. The user would benefit from seeing 2-4 rendered alternatives, code snippets, config examples, or ASCII UI previews.
5. A small batch of related, independent choices would unblock implementation.

Do not use ask_user_question for

• Plan approval.
• Generic “should I proceed?” confirmations.
• Open-ended brainstorming where choices are not naturally limited to 2-4 options.
• Questions you can answer by reading files, grepping, running tests, or inspecting docs first.
• Long menus. If you want 6+ options, narrow the decision before asking.
• Repeatedly asking the same question without new evidence.

Required workflow

1. Gather evidence first

Before asking, inspect the relevant code/docs/config when available. Do not ask the user to decide blind if you can provide context.

2. Decide if one question or a form is better

Use one question for one important decision.

Use multiple questions only when the decisions are:

• related,
• independent,
• each answerable without conditional follow-up,
• no more than 4 total.

If Q2 depends on Q1, ask Q1 first, wait for the answer, then ask Q2 in a later tool call.

3. Shape good options

Each question must have 2-4 options.

Options should be:

• mutually exclusive for single-select,
• independently selectable for multi-select,
• short and outcome-oriented,
• explained with a concise description.

Do not add an Other option. The UI adds Type something. automatically.

4. Use previews sparingly

Use preview only for single-select questions where visual/code/config comparison helps.

Good preview uses:

• ASCII UI mockups,
• code-style alternatives,
• config examples,
• diagrams.

Avoid preview for plain explanatory text; put that in description.

5. Continue correctly after the result

After the tool returns:

1. Read both the answer and any notes/annotations.
2. Restate the user's decision briefly.
3. Apply the decision.

If the result is declined/cancelled, do not continue as if a default was chosen. Stop and ask differently in plain text if the answer is required.

Payload examples

Single-select

{
  "questions": [
    {
      "question": "Which database should we use for the new service?",
      "header": "Database",
      "multiSelect": false,
      "options": [
        {
          "label": "PostgreSQL",
          "description": "Mature relational DB with strong consistency and JSON support."
        },
        {
          "label": "SQLite",
          "description": "Embedded and zero-config; good for local-first or single-node apps."
        }
      ]
    }
  ]
}

Multi-select

{
  "questions": [
    {
      "question": "Which CI checks should block merges?",
      "header": "CI gates",
      "multiSelect": true,
      "options": [
        { "label": "Unit tests", "description": "Fast correctness gate for core behavior." },
        { "label": "Type check", "description": "Catches API and integration mistakes." },
        { "label": "Lint", "description": "Keeps style and obvious errors consistent." },
        { "label": "E2E", "description": "Highest confidence but slower and flakier." }
      ]
    }
  ]
}

Preview-based single-select

{
  "questions": [
    {
      "question": "Which dashboard layout do you prefer?",
      "header": "Layout",
      "multiSelect": false,
      "options": [
        {
          "label": "Sidebar nav",
          "description": "Vertical nav on the left, content fills the rest.",
          "preview": "┌──────────────┐\n│ Nav │ Cards  │\n│     │ Chart  │\n└──────────────┘"
        },
        {
          "label": "Top tabs",
          "description": "Horizontal tabs above full-width content.",
          "preview": "┌──────────────┐\n│ Tab Tab Tab  │\n├──────────────┤\n│ Cards Chart  │\n└──────────────┘"
        }
      ]
    }
  ]
}

Anti-overasking rule

Ask at most one ask_user_question call per decision boundary in normal cases.

Ask a second time only if the user declined or the answer introduced materially new ambiguity. After that, stop and explain what is blocked rather than looping.