/requirements-clarity

name: requirements-clarity
description: Clarify ambiguous requirements through focused dialogue before implementation. Use when requirements are unclear, features are complex (>2 days), or involve cross-team coordination. Ask two core questions - Why? (YAGNI check) and Simpler? (KISS check) - to ensure clarity before coding.

Requirements Clarity Skill

Description

Automatically transforms vague requirements into actionable PRDs through systematic clarification with a 100-point scoring system.

Instructions

When invoked, detect vague requirements:

1. **Vague Feature Requests**

• User says: "add login feature", "implement payment", "create dashboard"
• Missing: How, with what technology, what constraints?

2. **Missing Technical Context**

• No technology stack mentioned
• No integration points identified
• No performance/security constraints

3. **Incomplete Specifications**

• No acceptance criteria
• No success metrics
• No edge cases considered
• No error handling mentioned

4. **Ambiguous Scope**

• Unclear boundaries ("user management" - what exactly?)
• No distinction between MVP and future enhancements
• Missing "what's NOT included"

**Do NOT activate when**:

• Specific file paths mentioned (e.g., "auth.go:45")
• Code snippets included
• Existing functions/classes referenced
• Bug fixes with clear reproduction steps

Core Principles

1. **Systematic Questioning**

• Ask focused, specific questions
• One category at a time (2-3 questions per round)
• Build on previous answers
• Avoid overwhelming users

2. **Quality-Driven Iteration**

• Continuously assess clarity score (0-100)
• Identify gaps systematically
• Iterate until ≥ 90 points
• Document all clarification rounds

3. **Actionable Output**

• Generate concrete specifications
• Include measurable acceptance criteria
• Provide executable phases
• Enable direct implementation

Clarification Process

Step 1: Initial Requirement Analysis

**Input**: User's requirement description

**Tasks**: 1. Parse and understand core requirement 2. Generate feature name (kebab-case format) 3. Determine document version (default `1.0` unless user specifies otherwise) 4. Ensure `./docs/prds/` exists for PRD output 5. Perform initial clarity assessment (0-100)

**Assessment 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

**Initial Response Format**:

I understand your requirement. Let me help you refine this specification.

**Current Clarity Score**: X/100

**Clear Aspects**:
- [List what's clear]

**Needs Clarification**:
- [List gaps]

Let me systematically clarify these points...

Step 2: Gap Analysis

Identify missing information across four dimensions:

**1. Functional Scope**

• What is the core functionality?
• What are the boundaries?
• What is out of scope?
• What are edge cases?

**2. User Interaction**

• How do users interact?
• What are the inputs?
• What are the outputs?
• What are success/failure scenarios?

**3. Technical Constraints**

• Performance requirements?
• Compatibility requirements?
• Security considerations?
• Scalability needs?

**4. Business Value**

• What problem does this solve?
• Who are the target users?
• What are success metrics?
• What is the priority?

Step 3: Interactive Clarification

**Question Strategy**: 1. Start with highest-impact gaps 2. Ask 2-3 questions per round 3. Build context progressively 4. Use user's language 5. Provide examples when helpful

**Question Format**:

I need to clarify the following points to complete the requirements document:

1. **[Category]**: [Specific question]?
   - For example: [Example if helpful]

2. **[Category]**: [Specific question]?

3. **[Category]**: [Specific question]?

Please provide your answers, and I'll continue refining the PRD.

**After Each User Response**: 1. Update clarity score 2. Capture new information in the working PRD outline 3. Identify remaining gaps 4. If score < 90: Continue with next round of questions 5. If score ≥ 90: Proceed to PRD generation

**Score Update Format**:

Thank you for the additional information!

**Clarity Score Update**: X/100 → Y/100

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

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

[If score < 90: Continue with next round of questions]
[If score ≥ 90: "Perfect! I will now generate the complete PRD document..."]

Step 4: PRD Generation

Once clarity score ≥ 90, generate comprehensive PRD.

**Output File**:

1. **Final PRD**: `./docs/prds/{feature_name}-v{version}-prd.md`

Use the `Write` tool to create or update this file. Derive `{version}` from the document version recorded in the PRD (default `1.0`).

PRD Document Structure

# {Feature Name} - Product Requirements Document (PRD)

## Requirements Description

### Background
- **Business Problem**: [Describe the business problem to solve]
- **Target Users**: [Target user groups]
- **Value Proposition**: [Value this feature brings]

### Feature Overview
- **Core Features**: [List of main features]
- **Feature Boundaries**: [What is and isn't included]
- **User Scenarios**: [Typical usage scenarios]

### Detailed Requirements
- **Input/Output**: [Specific input/output specifications]
- **User Interaction**: [User operation flow]
- **Data Requirements**: [Data structures and validation rules]
- **Edge Cases**: [Edge case handlin