| name | clarify |
| description | Review the current feature specification for product clarity, completeness, and edge cases. Product-focused only — no technical or implementation questions. |
Clarify Skill
Review specifications for product clarity and completeness. Focus exclusively on what the user experiences — not how it's built.
When to Activate
This skill is relevant when:
- Reviewing product specifications for ambiguity or gaps
- Checking that user-facing behavior is fully defined
- Validating feature scope and product value
- Identifying missing user flows and edge cases
Output File
Always write the review to a markdown file alongside the spec:
- Path:
<spec-directory>/clarification-review.md
- Every gap, question, and missing scenario must include a Recommendation — a concrete suggestion for what to add or change in the spec to resolve it.
- End the file with a Verdict:
APPROVED (no critical gaps) or NEEDS REVISION (critical/important gaps found).
Scope Boundary
IN SCOPE — Product questions:
- User flows, interactions, and behavior
- What the user sees, clicks, and experiences
- Business logic and rules
- Edge cases from the user's perspective
- Success metrics and acceptance criteria
- UX copy, states (empty, error, loading, success)
- Feature scope and prioritization
OUT OF SCOPE — Do NOT raise these:
- API design, endpoint structure, or request/response contracts
- Database schema, data models, or type definitions
- Code architecture, file structure, or refactoring concerns
- Performance implementation details (model choice, caching strategy)
- Prompt engineering or prompt structure
- Library/framework choices
- Existing code gaps or tech debt
- Anything that belongs in a technical plan, not a product spec
When in doubt, ask: "Would a product manager care about this?" If the answer is no, skip it.
Core Principles
Value Critical
- Does this solve a real user problem?
- Is the "why" clear?
- Strategic alignment with product vision
- Worth building?
Clarity & Completeness
- No ambiguous terms like "fast" or "easy"
- Detailed acceptance criteria for user-facing behavior
- Specific, measurable requirements
- All user scenarios covered
Scope Check
- Is this MVP or full roadmap?
- Should we cut scope to ship faster?
- Are there product blockers or dependencies?
- Realistic given constraints
Strategic Alignment
- Fits broader product vision
- Right priority for now
- Complements existing features
Quick Checks
When reviewing specifications, verify:
