interactive-questions

# Interactive Questions with the Question Tool Use the `question` tool to ask users structured, interactive questions with selectable options instead of plain yes/no or free-text prompts. This produces a numbered option list the user navigates with arrow keys and confirms with Enter. ## Core Rule **Never ask a yes/no question in plain text when the answer can be expressed as a set of options.** Always use the `question` tool with explicit choices. Wrong: > "Do you want to proceed? (yes/no)" Right: use the `question` tool with options such as "Proceed" and "Cancel". ## When to Use the Question Tool Use it whenever you need the user to make a decision: - **Confirmation** — before destructive or irreversible actions (delete, overwrite, push, deploy) - **Strategy selection** — when multiple valid approaches exist and user preference matters - **Clarification** — when a request is ambiguous and each interpretation leads to meaningfully different work - **Multi-step workflows** — to let the user steer direction between phases Do not use it for simple informational acknowledgement where no decision is required. ## How to Call the Question Tool The tool accepts an array of `questions`. Each question has: | Field | Required | Notes | |---|---|---| | `question` | yes | The full question text shown to the user | | `header` | yes | A very short label (max 30 chars) shown as the prompt title | | `options` | yes | Array of `{ label, description }` objects | | `multiple` | no | Set `true` to allow selecting more than one option | The tool automatically appends a "Type your own answer" option — do **not** add an "Other" catch-all yourself. ## Option Design Rules - **Label**: 1–5 words, concise action or noun phrase (e.g., "Proceed", "Cancel", "Edit message") - **Description**: one sentence explaining what that choice does (e.g., "Commit with the proposed message", "Abort the operation") - **Order**: put the recommended or most common option first; add `(Recommended)` at the end of its label when helpful - **Coverage**: include all meaningful paths — at minimum a "do it" option and a "cancel" option - **No duplicates**: each option must represent a distinct outcome ## Confirmation Pattern For any action that cannot easily be undone, use a three-option confirmation: ``` Proceed with <action>? 1. Proceed (Recommended) — <short description of what happens> 2. Cancel — Abort the operation 3. Edit / Adjust — <relevant alternative, e.g., "Provide a revised message"> ``` ## Strategy Selection Pattern When multiple valid approaches exist: ``` How should I handle <situation>? 1. <Approach A> (Recommended) — <one sentence tradeoff> 2. <Approach B> — <one sentence tradeoff> 3. <Approach C> — <one sentence tradeoff> ``` Always explain the tradeoff in the description so the user can decide without needing additional context. ## Clarification Pattern When a request is ambiguous, clarify before starting work rather than assuming: ``` What should <term / feature> include? 1. <Interpretation A> — <what this means concretely> 2. <Interpretation B> — <what this means concretely> ``` Limit clarification questions to genuine ambiguities. Do not ask about details you can decide using reasonable defaults. ## Multiple Selection Set `multiple: true` only when the user genuinely needs to pick more than one item — for example, selecting which files to include, which environments to target, or which checks to run. Keep the option list short (2–7 items) to avoid overwhelming the user. ## Avoid These Anti-Patterns | Anti-pattern | Problem | Fix | |---|---|---| | Asking yes/no in text | Requires typing; no structured response | Use `question` tool with Proceed / Cancel options | | Too many options (8+) | Overwhelming; hard to scan | Group related options or split into sequential questions | | Vague labels ("Option 1") | User cannot decide without reading description | Use action-oriented labels ("Deploy to staging") | | Catch-all "Other" option | Redundant — tool adds "Type your own answer" automatically | Remove it | | Asking every minor detail | Slows workflow; irritates user | Reserve questions for decisions that genuinely affect the outcome | | Multiple questions at once | Harder to process | Ask one question per tool call unless questions are tightly coupled | ## Quick Reference ``` question tool fields: questions[].question — full question text questions[].header — short label (≤30 chars) questions[].options[] .label — 1–5 words .description — one sentence questions[].multiple — true | false (default false) Do NOT add "Other" — tool appends "Type your own answer" automatically. Put recommended option first, label it "(Recommended)". ```