playbooks

home / skills / yellinzero / aico / clarification

clarification skill

/employees/pm/skills/clarification

This skill guides you through requirement clarification by asking one focused question at a time, offering options and reasoning to progress quickly.

npx playbooks add skill yellinzero/aico --skill clarification

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.9 KB
---
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

1. **SEARCH FIRST**: Always search `docs/reference/pm/` for related documents before asking questions
2. **ONE QUESTION AT A TIME**: Max 5 questions per session
3. **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

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

Overview

This skill resolves requirement ambiguities through structured, single-question interactions and expert recommendations. It prevents overwhelming stakeholders by asking one focused question at a time (up to five per session) and always including a recommended option with clear reasoning. Use it to unblock development by filling gaps in scope, behavior, data, and edge-case definitions.

How this skill works

The skill scans project PM reference docs first to avoid duplicate queries. It identifies the highest-impact ambiguity, formats a single multiple-choice question with context and implications, and provides a recommended option and rationale. Each answer should be documented back into the relevant story or version file after clarification.

When to use it

  • User runs /pm.clarify command or explicitly requests clarification
  • A stakeholder says "unclear", "not sure what this means", or similar
  • Requirements conflict or contain inconsistent details
  • User asks "what does X mean?" or "how should X work?"
  • Stories lack acceptance criteria or have gaps blocking development

Best practices

  • Search docs/reference/pm/ before asking any question to avoid duplicates
  • Always ask ONE question at a time and limit to five questions per session
  • Prioritize blocking issues: scope and security first, then UX and technical details
  • Provide 2–3 concrete options with trade-offs and a clear recommended choice
  • Record each clarification immediately in the relevant story/version files

Example use cases

  • Clarify whether a feature includes mobile sync or is web-only when scope is ambiguous
  • Decide expected behavior for an edge case (e.g., retry rules for failed payments)
  • Determine required data fields and validation rules when acceptance criteria are missing
  • Resolve conflicting requirements between product and legal about data retention
  • Establish error-handling behavior for offline scenarios before engineering work begins

FAQ

How many questions can I ask in one session?

Up to five questions per clarification session; each message must contain only one question.

What format will questions use?

Each question includes context, a short ambiguity statement, 2–3 options with implications, and a recommended option with reasoning.