home / skills / yellinzero / aico / aico-pm-clarification
This skill guides requirement clarification by asking one focused question at a time, offering recommended options and reasoning to prevent overload.
npx playbooks add skill yellinzero/aico --skill aico-pm-clarificationReview the files below or copy the command above to add this skill to your agents.
---
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
## 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
1. **Scan context**: Check `docs/reference/pm/` for existing documentation
2. **Identify ambiguities**: Categorize by type (scope, behavior, data, edge cases)
3. **Prioritize**: Sort by impact: scope > security > UX > technical
4. **Ask ONE question at a time**: Max 5 questions per session
5. **Provide recommendation**: Each question should have a recommended option with reasoning
6. **Update docs**: Document each answer immediately
## Question Format
```markdown
### 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
This skill resolves requirement ambiguities through a structured, one-question-at-a-time approach. It prevents overwhelming stakeholders by asking a single focused question per message, offering recommended options and the reasoning behind each choice. The goal is to surface blocking decisions so development can proceed with clear acceptance criteria.
The skill scans project context and requirement docs to identify ambiguous items and categorizes them by scope, behavior, data, edge cases, or error handling. For each ambiguity it poses exactly one multiple-choice question with a recommended option and concise reasoning. It limits sessions to a maximum of five questions and records answers to update documentation immediately.
How many questions will you ask in one session?
Up to five questions per clarification session, with only one question asked at a time.
What format do questions use?
Each question is multiple choice with a short context quote, ambiguity description, options with implications, and a recommended option with reasoning.