aico-pm-clarification_skill

Overview

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.

How this skill works

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.

When to use it

• When a user runs /pm.clarify or requests clarification in chat
• If a requirement contains conflicting or missing details
• When stories lack acceptance criteria or have unclear behavior
• If stakeholders say 'unclear', 'not sure what this means', or 'confused about'
• Before development begins and information gaps block progress

Best practices

• Ask only one focused question per message to avoid cognitive overload
• Prioritize blocking issues first: scope and security, then UX and technical details
• Provide 2–3 clear options for each question and state trade-offs
• Always include a recommended option and short reasoning to guide decision-making
• Document each resolved ambiguity immediately in project docs

Example use cases

• Clarifying whether a feature includes admin-only controls or is available to all users
• Deciding expected behavior for ambiguous edge cases (e.g., empty inputs or timeouts)
• Choosing between data retention durations when requirements omit storage rules
• Resolving conflicting acceptance criteria between product and engineering
• Filling gaps in stories so QA can write deterministic tests