| name | aico-pm-clarification |
| description | Resolve requirement ambiguities through STRUCTURED questioning: one question at a time, with recommended options and reasoning.
UNIQUE VALUE: Prevents overwhelming users with multiple questions. Provides expert recommendations for each decision.
Use this skill when:
- Running /pm.clarify command
- User says "unclear", "not sure what this means", "confused about"
- User asks "what does X mean?", "how should X work?", "can you clarify?"
- Requirements have conflicting or inconsistent details
- Stories are missing acceptance criteria or have gaps
- Need to fill information gaps BEFORE development can proceed
Process: Ask ONE question at a time (max 5 per session), provide recommended option with reasoning.
DO NOT ask multiple questions at once - this overwhelms users.
|
Requirement Clarification
⚠️ CRITICAL RULES - READ FIRST
- SEARCH FIRST: Always search
docs/reference/pm/ for related documents before asking questions
- ONE QUESTION AT A TIME: Max 5 questions per session
- UPDATE DOCUMENTS: After clarification, update the relevant story/version files
Language Configuration
Before generating any content, check aico.json in project root for language field to determine the output language. If not set, default to English.
Process
- Scan context: Check
docs/reference/pm/ for existing documentation
- Identify ambiguities: Categorize by type (scope, behavior, data, edge cases)
- Prioritize: Sort by impact: scope > security > UX > technical
- Ask ONE question at a time: Max 5 questions per session
- Provide recommendation: Each question should have a recommended option with reasoning
- Update docs: Document each answer immediately
Question Format
### Question [N]: [Topic]
**Context**: [Quote relevant requirement]
**Ambiguity**: [What's unclear]
**Options**:
| Option | Description | Implications |
|--------|-------------|--------------|
| A | [First option] | [Trade-offs] |
| B | [Second option] | [Trade-offs] |
**Recommended**: [Option] because [reasoning]
Ambiguity Categories
| Category | Focus |
|---|
| Scope | What's included/excluded |
| Behavior | How feature should work |
| Data | What information is needed |
| Edge cases | Unusual scenarios |
| Error handling | Failure modes |
Key Rules
- ALWAYS ask ONE question per message, never batch
- MUST provide recommended option with reasoning for each question
- ALWAYS prioritize blocking issues (scope, security) over minor details
- Max 5 questions per clarification session
Common Mistakes
- ❌ Ask all questions at once → ✅ One at a time
- ❌ Open-ended questions → ✅ Multiple choice with recommendation
- ❌ Low-impact questions → ✅ Focus on blocking issues first
