Ask Questions If Underspecified
Goal
Ask the minimum set of clarifying questions needed to avoid wrong work; 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
Treat a request as underspecified if after exploring how to perform the work, 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 1-5 questions in the first pass. Prefer questions that eliminate whole branches of work.
Use the question tool to present structured choices:
- Offer multiple-choice options with clear labels
- Mark recommended defaults with "(Recommended)" in the label
- Use
multiple: true when the user can select several options
- The user can always select "Other" for custom input
3) Pause before acting
Until must-have answers arrive:
- Do not run commands, edit files, or produce a detailed plan that depends on unknowns
- 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.
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.
1---2name: ask-questions-if-underspecified-23description: Clarify requirements before implementing. Use when serious doubts arise.4---5
6# Ask Questions If Underspecified
7
8## Goal
9
10Ask the minimum set of clarifying questions needed to avoid wrong work; do not start implementing until the must-have questions are answered (or the user explicitly approves proceeding with stated assumptions).
11
12## Workflow
13
14### 1) Decide whether the request is underspecified
15
16Treat a request as underspecified if after exploring how to perform the work, some or all of the following are not clear:
17- Define the objective (what should change vs stay the same)
18- Define "done" (acceptance criteria, examples, edge cases)
19- Define scope (which files/components/users are in/out)
20- Define constraints (compatibility, performance, style, deps, time)
21- Identify environment (language/runtime versions, OS, build/test runner)
22- Clarify safety/reversibility (data migration, rollout/rollback, risk)
23
24If multiple plausible interpretations exist, assume it is underspecified.
25
26### 2) Ask must-have questions first (keep it small)
27
28Ask 1-5 questions in the first pass. Prefer questions that eliminate whole branches of work.
29
30Use the `question` tool to present structured choices:
31- Offer multiple-choice options with clear labels
32- Mark recommended defaults with "(Recommended)" in the label
33- Use `multiple: true` when the user can select several options
34- The user can always select "Other" for custom input
35
36### 3) Pause before acting
37
38Until must-have answers arrive:
39- Do not run commands, edit files, or produce a detailed plan that depends on unknowns
40- 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)
41
42If the user explicitly asks you to proceed without answers:
43- State your assumptions as a short numbered list
44- Ask for confirmation; proceed only after they confirm or correct them
45
46### 4) Confirm interpretation, then proceed
47
48Once you have answers, restate the requirements in 1-3 sentences (including key constraints and what success looks like), then start work.
49
50## Anti-patterns
51
52- Don't ask questions you can answer with a quick, low-risk discovery read (e.g., configs, existing patterns, docs).
53- Don't ask open-ended questions if a tight multiple-choice or yes/no would eliminate ambiguity faster.
diegosouzapw