Requirements Clarity

/requirements-clarity

Transform vague requirements into actionable, testable requirements through systematic clarification with a 100-point scoring system. This skill produces the clarified requirements document; when the user wants the full spec written from an already-clear idea, hand off to write-spec or idea-to-spec.

When to Activate

1. Vague feature requests: "add login feature", "implement payment", "create dashboard" with no how, technology, or constraints
2. Missing technical context: no stack, integration points, or performance/security constraints mentioned
3. Incomplete specifications: no acceptance criteria, success metrics, edge cases, or error handling
4. Ambiguous scope: unclear boundaries, no MVP vs future distinction, no "what's NOT included"

Do NOT activate when: specific file paths or code snippets are given, existing functions are referenced, or it is a bug fix with clear reproduction steps.

Core Principles

1. Systematic questioning: ask focused, specific questions, one category at a time (2-3 questions per round), building on previous answers. Along the way apply two core checks: Why? (YAGNI check) and Simpler? (KISS check).
2. Quality-driven iteration: continuously assess a clarity score (0-100), identify gaps, iterate until >= 90 points.
3. Actionable output: concrete specifications, measurable acceptance criteria, executable phases.

Clarification Process

Step 1: Initial Requirement Analysis

Parse the requirement, name the feature (kebab-case), and score initial clarity against this rubric:

Functional Clarity: /30 points
- Clear inputs/outputs: 10 pts
- User interaction defined: 10 pts
- Success criteria stated: 10 pts

Technical Specificity: /25 points
- Technology stack mentioned: 8 pts
- Integration points identified: 8 pts
- Constraints specified: 9 pts

Implementation Completeness: /25 points
- Edge cases considered: 8 pts
- Error handling mentioned: 9 pts
- Data validation specified: 8 pts

Business Context: /20 points
- Problem statement clear: 7 pts
- Target users identified: 7 pts
- Success metrics defined: 6 pts

Open with: current clarity score, what is already clear, and what needs clarification.

Step 2: Gap Analysis

Identify missing information across four dimensions:

1. Functional scope: core functionality, boundaries, out of scope, edge cases
2. User interaction: how users interact, inputs, outputs, success/failure scenarios
3. Technical constraints: performance, compatibility, security, scalability
4. Business value: problem solved, target users, success metrics, priority

Step 3: Interactive Clarification

• Start with the highest-impact gaps; ask 2-3 questions per round
• Build context progressively, use the user's language, give examples when helpful
• After each response: update the score, capture new information, list remaining gaps
• Score < 90: continue with the next round. Score >= 90: proceed to the requirements document

Score update format:

**Clarity Score Update**: X/100 -> Y/100

**New Clarified Content**:
- [Summarize new information]

**Remaining Points to Clarify**:
- [List remaining gaps if score < 90]

Step 4: Requirements Document

Once clarity >= 90, deliver the complete requirements document as a chat artifact (or write it to docs/prds/{feature-name}-v{version}-prd.md if working in a repo), structured as:

• Requirements Description: background (business problem, target users, value), feature overview (core features, boundaries, user scenarios), detailed requirements (input/output, interaction, data, edge cases)
• Design Decisions: technical approach, constraints, risk assessment
• Acceptance Criteria: checklistable functional, quality, and user acceptance items (- [ ] format)
• Execution Phases: preparation, core development, integration and testing, deployment, each with concrete tasks, deliverables, and time estimates

Behavioral Guidelines

Do: ask specific targeted questions, build on previous answers, provide examples, summarize clarification rounds, generate concrete specifications, stay in clarification mode until score >= 90.

Don't: ask all questions at once, make assumptions without confirmation, generate the document before a 90+ score, use vague language, proceed without user responses.

Success Criteria

• Clarity score >= 90/100
• All sections complete with substance
• Acceptance criteria checklistable
• Execution phases actionable with concrete tasks
• User approves the final document; ready for spec-writing or development handoff

Usage

/requirements-clarity $ARGUMENTS