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 optimizationAfter 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
| # | Question | Answer | Category |
|---|----------|--------|----------|
| 1 | [Question 1] | [Answer 1] | Functional Scope |
| 2 | [Question 2] | [Answer 2] | Data Model |
| ... | ... | ... | ... |
### Coverage Summary
| Category | Status |
|----------|--------|
| Functional Scope | Resolved |
| Domain & Data Model | Clear |
| Integration & Dependencies | Deferred |
| ... | ... |
### 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