Ask Questions If Underspecified

When to Use

Use this skill when a request has multiple plausible interpretations or key details (objective, scope, constraints, environment, or safety) are unclear.

This is the default clarification path for simple/low-risk tasks. If the task appears medium/high complexity, route to brainstorming instead.

When NOT to Use

Do not use this skill when the request is already clear, or when a quick, low-risk discovery read can answer the missing details.

Goal

Ask the minimum set of clarifying questions needed to avoid wrong work. Default to the request_user_input tool for 1-3 short structured questions (if the tool is available in the current mode). Do not start implementing until the must-have questions are answered (or the user explicitly approves proceeding with stated assumptions).

Workflow

1) Decide whether the request is underspecified

First, perform a quick, low-risk exploration of the project context (read relevant files, configs, existing patterns) to understand the current state. Do not make changes during this step.

Then, treat a request as underspecified if some or all of the following are not clear:

Define the objective (what should change vs stay the same)
Define "done" (acceptance criteria, examples, edge cases)
Define scope (which files/components/users are in/out)
Define constraints (compatibility, performance, style, deps, time)
Identify environment (language/runtime versions, OS, build/test runner)
Clarify safety/reversibility (data migration, rollout/rollback, risk)

If multiple plausible interpretations exist, assume it is underspecified.

2) Ask must-have questions first (keep it small)

Ask up to 5 questions total in the first pass (1-3 per request_user_input call). Prefer questions that eliminate whole branches of work.

Tool requirement:

If clarification is required and request_user_input is available, MUST use request_user_input instead of plain chat questions by default.
Ask 1-3 short, high-leverage questions per request_user_input call.
If request_user_input is unavailable in the current mode, state that briefly and ask the same questions directly in chat.

Make questions easy to answer:

Optimize for scannability (short, numbered questions; avoid paragraphs)
Offer multiple-choice options when possible
Suggest reasonable defaults when appropriate (mark them clearly as the default/recommended choice; bold the recommended choice in the list, or if you present options in a code block, put a bold "Recommended" line immediately above the block and also tag defaults inside the block)
Include a fast-path response (e.g., reply defaults to accept all recommended/default choices)
Include a low-friction "not sure" option when helpful (e.g., "Not sure - use default")
Separate "Need to know" from "Nice to know" if that reduces friction
Structure options so the user can respond with compact decisions (e.g., 1b 2a 3c); restate the chosen options in plain language to confirm

3) Pause before acting

Until must-have answers arrive:

Do not run commands, edit files, produce a detailed plan, or begin implementation in any form
If request_user_input was used, wait for its answers before continuing
Do perform a clearly labeled, low-risk discovery step only if it does not commit you to a direction (e.g., inspect repo structure, read relevant config files)

If the user explicitly asks you to proceed without answers:

State your assumptions as a short numbered list
Ask for confirmation; proceed only after they confirm or correct them

4) Confirm interpretation, then proceed

Once you have answers, restate the requirements in 1-3 sentences (including key constraints and what success looks like), then start work.

Question templates

"Before I start, I need: (1) ..., (2) ..., (3) .... If you don't care about (2), I will assume ...."
"Which of these should it be? A) ... B) ... C) ... (pick one)"
"What would you consider 'done'? For example: ..."
"Any constraints I must follow (versions, performance, style, deps)? If none, I will target the existing project defaults."
Use numbered questions with lettered options and a clear reply format

1) Scope?
   a) Minimal change (default)
   b) Refactor while touching the area
   c) Not sure - use default

2) Compatibility target?
   a) Current project defaults (default)
   b) Also support older versions: <specify>
   c) Not sure - use default

Reply: defaults (or 1a 2a)

Anti-patterns

Don't ask questions you can answer with a quick, low-risk discovery read (e.g., configs, existing patterns, docs).
Don't ask open-ended questions if a tight multiple-choice or yes/no would eliminate ambiguity faster.

ask-questions-if-underspecified