Clarify Skill

Purpose: Detect and reduce ambiguity in feature requests by asking targeted clarification questions and updating plans with the results.

User Input: "${ARGUMENTS}"

If the input above is empty, ask the user using AskUserQuestion: "What feature, bug, or improvement would you like to clarify? Please provide a brief description."

Do not proceed until you have input to clarify.

Stage 1: Ambiguity & Coverage Scan

Analyze the user input against this taxonomy. For each category, mark status: Clear / Partial / Missing.

Taxonomy Categories

Category What to Check

Functional Scope Core user goals, success criteria, out-of-scope declarations

Domain & Data Model Entities, attributes, relationships, identity rules, state transitions

Interaction & UX Flow User journeys, error/empty/loading states, accessibility

Non-Functional Requirements Performance targets, scalability, reliability, security, observability

Integration & Dependencies External services/APIs, data formats, failure modes

Edge Cases & Errors Negative scenarios, rate limiting, conflict resolution

Constraints & Tradeoffs Technical constraints, explicit tradeoffs, rejected alternatives

Terminology Canonical terms, avoided synonyms

Coverage Assessment

After scanning, produce an internal coverage map:

• Clear: Sufficient information provided

• Partial: Some information but gaps exist

• Missing: No information provided, critical for implementation

Stage 2: Generate Clarification Questions

Based on the coverage scan, generate a prioritized queue of up to 5 questions.

Question Constraints

Each question must be:

• Answerable with multiple choice (2-5 options) OR short answer (≤5 words)

• High impact: Materially affects architecture, data modeling, task decomposition, or testing

• Not already answered in the user input

• Not trivial stylistic preferences

Question Prioritization

Prioritize by: Impact × Uncertainty

• Cover highest-impact unresolved categories first

• Avoid asking two low-impact questions when a high-impact area is unresolved

Stage 3: Sequential Questioning (Using AskUserQuestion Tool)

IMPORTANT: Use the AskUserQuestion tool to present each question. Present ONE question at a time.

For Multiple-Choice Questions

Analyze options and determine the most suitable based on:

• Best practices for the project type

• Common patterns in similar implementations

• Risk reduction (security, performance, maintainability)

Use AskUserQuestion with options:

• Put recommended option first with "(Recommended)" suffix

• Provide 2-4 clear options

• Include description for each option

Example AskUserQuestion call:

Question: "How should user authentication be handled?" Options:

• "JWT tokens (Recommended)" - Stateless, scalable, industry standard
• "Session-based" - Server-side sessions with cookies
• "OAuth only" - Delegate to third-party providers

For Short-Answer Questions

Use AskUserQuestion with options that include common choices:

Question: "What is the expected maximum number of concurrent users?" Options:

• "< 100 users" - Small scale, simple infrastructure
• "100-1000 users" - Medium scale, may need caching
• "1000+ users (Recommended)" - Large scale, requires optimization

After Each Answer

• Record the answer

• Move to next question

• Stop when: all critical ambiguities resolved, user signals "done", or 5 questions asked

Stage 4: Update Plan with Clarifications

After all questions are answered, append clarifications to the plan file.

If plan file exists (plans/<topic>.md ):

Add a new section to the plan:

Clarifications

Session: [DATE]

Questions & Answers

Coverage Summary

Key Decisions

• [Decision 1]: [Rationale based on answer]
• [Decision 2]: [Rationale based on answer]

If plan file does not exist:

Create a new clarifications file at plans/clarifications-<topic>.md with the same format, which can be referenced when running /core:plan .

Stage 5: Next Steps

Use AskUserQuestion to present options:

Question: "Clarification complete. [X] questions answered. Plan updated. What would you like to do next?"

Options:

• Run /core:plan

• Create/update the plan with these clarifications (Recommended)

• Ask more questions - Continue clarifying specific areas

• View clarifications - Show the clarifications section that was added

• Start over - Reset and re-clarify from scratch

Behavior Rules

• Always use AskUserQuestion tool for gathering user input

• If no meaningful ambiguities found → "No critical ambiguities detected. Ready for /core:plan ."

• Never exceed 5 questions total

• Respect early termination signals ("done", "stop", "proceed")

• Do not ask speculative tech stack questions unless blocking functional clarity

• Always update the plan file with clarifications after completion