Requirements Clarity

<!-- AUTO-GENERATED by export-skills.py — DO NOT EDIT -->
---
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)

| Criterion | Points |
|---|---|
| Clear inputs/outputs defined | 10 |
| User interaction flow described | 10 |
| Success criteria stated | 10 |

### Technical Specificity (25 pts)

| Criterion | Points |
|---|---|
| Technology stack mentioned | 8 |
| Integration points identified | 8 |
| Constraints specified (performance, security, scale) | 9 |

### Implementation Completeness (25 pts)

| Criterion | Points |
|---|---|
| Edge cases considered | 8 |
| Error handling mentioned | 9 |
| Data validation specified | 8 |

### Business Context (20 pts)

| Criterion | Points |
|---|---|
| Problem statement clear | 7 |
| Target users identified | 7 |
| Success metrics defined | 6 |

## Process

### Step 1: Initial Assessment

Parse the requirement and score it:

```markdown
**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:

```markdown
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:

```markdown
**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:

```markdown
# {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

| Avoid | Why | Instead |
|---|---|---|
| Starting to code with vague requirements | Rework, wasted effort | Clarify first, code second |
| Accepting "make it nice" | Not testable | Define specific visual criteria |
| Skipping edge cases | Production bugs | Ask "what if X fails/is empty/is huge?" |
| No success metrics | Can't measure completion | Define measurable outcomes |
| Scope creep during clarification | Never reaches 90 | Separate MVP from future enhancements |

## References

- Based on [softaworks/agent-toolkit requirements-clarity](https://github.com/softaworks/agent-toolkit/tree/main/skills/requirements-clarity) (MIT License)

<!-- Source: .faos/custom/skills/business/requirements-clarity/SKILL.md -->