Requirements Clarity

name: requirements-clarity description: Clarify ambiguous requirements through focused dialogue before implementation. Use when requirements are unclear, features are complex (>2 days of work), or involve cross-team coordination. Applies a 100-point scoring system across 4 dimensions (functional clarity, technical specificity, implementation completeness, business context) to systematically transform vague requests into actionable PRDs. tags: [requirements, prd, clarity, planning]

Requirements Clarity

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

When to Use

• "Add login feature" -- missing: how, what technology, what constraints
• "Implement payment" -- missing: provider, flow, error handling
• "Create dashboard" -- missing: what data, for whom, what decisions
• Any feature request missing acceptance criteria, success metrics, or edge cases
• Complex features (>2 days estimated work)
• Cross-team coordination needed

When NOT to Use

• Specific file paths mentioned ("fix auth.go:45")
• Code snippets included
• Bug fixes with clear reproduction steps
• Simple, well-defined tasks

Two Core Questions

Before any implementation, ask:

1. Why? (YAGNI check) -- Is this actually needed? What problem does it solve?
2. Simpler? (KISS check) -- Is there a simpler way to achieve the same goal?

Scoring System (100 points)

Functional Clarity (30 pts)

Technical Specificity (25 pts)

Implementation Completeness (25 pts)

Business Context (20 pts)

Process

Step 1: Initial Assessment

Parse the requirement and score it:

**Current Clarity Score**: X/100

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

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

Step 2: Gap Analysis

Identify missing information across 4 dimensions:

Functional Scope: What is the core functionality? What are the boundaries? What is out of scope? What are edge cases?

User Interaction: How do users interact? What are the inputs/outputs? What are success/failure scenarios?

Technical Constraints: Performance requirements? Compatibility? Security considerations? Scalability needs?

Business Value: What problem does this solve? Who are the target users? What are success metrics? What is the priority?

Step 3: Interactive Clarification

Ask 2-3 focused questions per round, starting with highest-impact gaps:

I need to clarify the following:

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

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

After each response, update the score:

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

**Remaining gaps**:
- [List if score < 90]

Continue until score >= 90.

Step 4: PRD Generation

Once clarity score >= 90, generate a structured PRD:

# {Feature Name} - PRD

## Background
- **Business Problem**: [What problem this solves]
- **Target Users**: [Who uses this]
- **Value Proposition**: [Why it matters]

## Requirements
- **Core Features**: [What it does]
- **Boundaries**: [What's in/out of scope]
- **User Scenarios**: [How users interact]
- **Edge Cases**: [Boundary conditions]

## Technical Approach
- **Architecture**: [Key decisions and rationale]
- **Components**: [Main technical components]
- **Constraints**: [Performance, security, scale]

## Acceptance Criteria
- [ ] [Specific, testable criterion]
- [ ] [Specific, testable criterion]
- [ ] [Specific, testable criterion]

## Execution Phases
### Phase 1: [Name]
- [ ] [Task with deliverable]
- [ ] [Task with deliverable]

### Phase 2: [Name]
- [ ] [Task with deliverable]

## Risk Assessment
| Risk | Impact | Mitigation |
|---|---|---|
| [Description] | High/Med/Low | [Plan] |

---
**Clarity Score**: {score}/100
**Clarification Rounds**: {rounds}

Guidelines

DO

• Ask specific, targeted questions (not open-ended)
• Build on previous answers
• Provide examples to guide users
• Summarize what you've learned each round
• Stay in clarification mode until score >= 90
• Generate concrete, testable acceptance criteria

DON'T

• Ask all questions at once (overwhelming)
• Make assumptions without confirmation
• Generate PRD before reaching 90+ score
• Use vague or abstract language in the PRD
• Skip any required sections
• Accept "it should just work" as a requirement

Anti-Patterns

References

• Based on softaworks/agent-toolkit requirements-clarity (MIT License)