Requirements Decomposition

Transform a PROBLEM_BRIEF.md artifact into a comprehensive REQUIREMENTS.md artifact containing functional requirements, user stories, and non-functional requirements. This is the second step in the greenfield specification pipeline — it takes a well-defined problem and produces actionable, testable requirements.

When to Use This Skill

• A PROBLEM_BRIEF.md exists and has been reviewed
• You need to define what the system must do before writing specifications
• Stakeholders need a prioritized list of requirements for planning
• User stories are needed for sprint planning or backlog creation

Pipeline Position

[Raw Idea] → [PROBLEM_BRIEF.md] → **REQUIREMENTS DECOMPOSITION** → [REQUIREMENTS.md] → Specification Writing → ...

Input: artifacts/greenfield/<project_name>/PROBLEM_BRIEF.md Output: artifacts/greenfield/<project_name>/REQUIREMENTS.md

Process

Step 1: Read and Analyze Problem Brief

Load the PROBLEM_BRIEF.md and extract:

• Problem statement (defines the scope boundary)
• Target users (each user type generates requirements)
• Success metrics (each metric implies at least one requirement)
• Constraints (limit what requirements can demand)
• Non-goals (explicitly excluded from requirements)
• Assumptions (may generate conditional requirements)
• Open questions (may block certain requirements)

Cross-reference every requirement back to problem brief elements using their IDs (SM-NNNN, CON-NNNN, etc.).

Step 2: Identify Functional Areas

Group the problem space into logical functional areas. Each area becomes a category for requirements.

Common functional areas:

• User Management (authentication, authorization, profiles)
• Core Business Logic (the primary value proposition)
• Data Management (storage, retrieval, transformation)
• Integration (external systems, APIs, third-party services)
• Reporting & Analytics (dashboards, exports, metrics)
• Communication (notifications, messaging, alerts)
• Administration (system config, user management, monitoring)

Each functional area should map to at least one requirement.

Step 3: Decompose into Functional Requirements

For each functional area, create requirements with the following structure:

Requirement format:

REQ-NNNN: [Requirement Title]
Priority: P0 | P1 | P2
Functional Area: [Area Name]
Description: [Detailed description of what the system must do]
Rationale: [Why this requirement exists — link to SM-NNNN, user type, or problem statement]
Dependencies: [REQ-NNNN of other requirements this depends on, or "None"]
Acceptance Criteria:
  - [Testable criterion 1]
  - [Testable criterion 2]
  - [Testable criterion 3]

Priority levels:

Priority	Label	Definition	Planning Impact
P0	Must-Have	System is unusable without this. Required for MVP.	Must be in Phase 1 / Sprint 1-2
P1	Should-Have	Important for user satisfaction but system functions without it.	Target Phase 1-2
P2	Nice-to-Have	Enhances experience but can be deferred indefinitely.	Phase 3+ or backlog

Rules for requirements:

• Each requirement must be testable (has clear acceptance criteria)
• Each requirement must trace back to the problem brief (rationale field)
• Each requirement must have exactly one priority level
• Requirements must not contradict constraints from the problem brief
• Requirements must not overlap with non-goals from the problem brief

Step 4: Write User Stories

For each functional requirement, create at least one user story:

User story format:

US-NNNN: [User Story Title]
Parent: REQ-NNNN
User Type: [From problem brief target users table]
Story: As a [user type], I want to [action] so that [benefit].
Acceptance Criteria:
  - Given [precondition], when [action], then [expected result]
  - Given [precondition], when [action], then [expected result]

Rules for user stories:

• Every REQ must have at least one user story
• P0 requirements should have 2-3 user stories covering primary flows
• User types must match those defined in the problem brief
• Acceptance criteria must use Given/When/Then format
• Stories must be independent (completable without other stories)
• Stories must be estimable (small enough to estimate effort)

Step 5: Define Non-Functional Requirements

Create NFRs covering the standard quality attributes. Each NFR must have measurable criteria.

NFR Categories (all must be addressed):

Category	Focus Areas	Example Metrics
Performance	Response time, throughput, latency	p95 < 200ms, 1000 RPS
Security	Authentication, authorization, data protection	OWASP Top 10, encryption at rest
Scalability	Horizontal/vertical growth, data volume	10x user growth, 1M records
Usability	Accessibility, learnability, error handling	WCAG 2.1 AA, < 5 min onboarding
Reliability	Uptime, fault tolerance, disaster recovery	99.9% uptime, RPO < 1h, RTO < 4h

NFR format:

NFR-NNNN: [NFR Title]
Category: [Performance | Security | Scalability | Usability | Reliability]
Description: [What quality attribute must be maintained]
Metric: [Measurable target]
Measurement Method: [How to verify compliance]
Priority: P0 | P1 | P2

Rules for NFRs:

• At least one NFR per category (Performance, Security, Scalability, Usability, Reliability)
• Each NFR must have a measurable metric
• NFRs must not contradict constraints from the problem brief
• Security NFRs should reference relevant standards (OWASP, SOC2, HIPAA, etc.)
• Performance NFRs should specify percentile targets (p50, p95, p99)

Step 6: Validate and Cross-Reference

Before writing the artifact, validate:

1. Every success metric (SM-NNNN) from the problem brief maps to at least one REQ
2. No requirement contradicts a constraint (CON-NNNN)
3. No requirement overlaps with a non-goal (NG-NNNN)
4. Every REQ has at least one user story
5. All five NFR categories are covered
6. Dependencies form a valid DAG (no circular dependencies)
7. Priority distribution is reasonable (not everything is P0)

Output Format

Write the artifact following the template at ${CLAUDE_PLUGIN_ROOT}/reference/templates/REQUIREMENTS.template.md.

The artifact must follow the standard artifact template structure:

# REQUIREMENTS: [Project Name]

## Summary
[2-3 sentence summary of the requirements scope, count of REQs by priority, and relationship to the problem brief]

## Inputs
- **Problem Brief**: `PROBLEM_BRIEF.md` — [reference to problem statement]
- **Success Metrics**: [SM-NNNN IDs referenced]
- **Constraints**: [CON-NNNN IDs that limit requirements]

## Outputs
- This document (REQUIREMENTS.md)
- Feeds into: FUNCTIONAL_SPEC.md (via specification-writing skill)
- Feeds into: VIABILITY.md (via business-viability skill)

## Assumptions
- [ASM-0001]: [Assumption text — inherited from problem brief or new]
- ...

## Open Questions
- [OQ-0001]: [Question that blocks or affects specific requirements]
- ...

## Main Content

### Requirements Summary

| Priority | Count | Description |
|----------|-------|-------------|
| P0 (Must-Have) | [N] | [Brief description of P0 scope] |
| P1 (Should-Have) | [N] | [Brief description of P1 scope] |
| P2 (Nice-to-Have) | [N] | [Brief description of P2 scope] |
| **Total** | **[N]** | |

### Traceability Matrix

| Success Metric | Requirements | Coverage |
|---------------|-------------|----------|
| SM-0001: [Name] | REQ-0001, REQ-0003 | Full |
| SM-0002: [Name] | REQ-0002 | Partial |
| ... | ... | ... |

### Functional Requirements

#### [Functional Area 1]

**REQ-0001: [Requirement Title]**
- **Priority**: P0
- **Functional Area**: [Area Name]
- **Description**: [Detailed description]
- **Rationale**: Supports SM-0001; addresses [user type] need for [capability]
- **Dependencies**: None
- **Acceptance Criteria**:
  - [Testable criterion 1]
  - [Testable criterion 2]
  - [Testable criterion 3]

**REQ-0002: [Requirement Title]**
- **Priority**: P1
- **Functional Area**: [Area Name]
- **Description**: [Detailed description]
- **Rationale**: Supports SM-0002; enables [user type] to [action]
- **Dependencies**: REQ-0001
- **Acceptance Criteria**:
  - [Testable criterion 1]
  - [Testable criterion 2]

[... additional requirements ...]

#### [Functional Area 2]

[... requirements for area 2 ...]

### User Stories

#### Stories for REQ-0001: [Requirement Title]

**US-0001: [User Story Title]**
- **Parent**: REQ-0001
- **User Type**: [From problem brief]
- **Story**: As a [user type], I want to [action] so that [benefit].
- **Acceptance Criteria**:
  - Given [precondition], when [action], then [expected result]
  - Given [precondition], when [action], then [expected result]

**US-0002: [User Story Title]**
- **Parent**: REQ-0001
- **User Type**: [From problem brief]
- **Story**: As a [user type], I want to [action] so that [benefit].
- **Acceptance Criteria**:
  - Given [precondition], when [action], then [expected result]

[... additional user stories grouped by parent REQ ...]

### Non-Functional Requirements

#### Performance

**NFR-0001: [NFR Title]**
- **Category**: Performance
- **Description**: [Quality attribute description]
- **Metric**: [Measurable target, e.g., "API response time p95 < 200ms"]
- **Measurement Method**: [How to verify, e.g., "Load testing with k6 at 500 concurrent users"]
- **Priority**: P0

#### Security

**NFR-0002: [NFR Title]**
- **Category**: Security
- **Description**: [Quality attribute description]
- **Metric**: [Measurable target]
- **Measurement Method**: [How to verify]
- **Priority**: P0

#### Scalability

**NFR-0003: [NFR Title]**
- **Category**: Scalability
- **Description**: [Quality attribute description]
- **Metric**: [Measurable target]
- **Measurement Method**: [How to verify]
- **Priority**: P1

#### Usability

**NFR-0004: [NFR Title]**
- **Category**: Usability
- **Description**: [Quality attribute description]
- **Metric**: [Measurable target]
- **Measurement Method**: [How to verify]
- **Priority**: P1

#### Reliability

**NFR-0005: [NFR Title]**
- **Category**: Reliability
- **Description**: [Quality attribute description]
- **Metric**: [Measurable target]
- **Measurement Method**: [How to verify]
- **Priority**: P0

### Dependency Graph

```mermaid
graph TD
    REQ-0001 --> REQ-0002
    REQ-0001 --> REQ-0003
    REQ-0002 --> REQ-0005
    REQ-0003 --> REQ-0004

Acceptance Criteria

• Every success metric (SM-NNNN) from the problem brief maps to at least one REQ
• No requirement contradicts a constraint (CON-NNNN) from the problem brief
• No requirement overlaps with a non-goal (NG-NNNN) from the problem brief
• Every REQ has at least one user story (US-NNNN)
• All five NFR categories are addressed (Performance, Security, Scalability, Usability, Reliability)
• All IDs are sequential and sorted appropriately
• Priority distribution is reasonable (not all P0)
• Dependencies form a valid DAG (no circular dependencies)
• User stories use Given/When/Then acceptance criteria format
• Traceability matrix shows complete coverage of success metrics

**Output path**: `artifacts/greenfield/<project_name>/REQUIREMENTS.md`

## Determinism Rules

1. REQ-NNNN IDs: Sort alphabetically by requirement title, assign sequential 4-digit numbers starting from 0001
2. US-NNNN IDs: Sort by parent REQ ID first, then alphabetically by story title within each REQ group, assign sequential 4-digit numbers starting from 0001 globally (not per-REQ)
3. NFR-NNNN IDs: Sort by category order (Performance, Security, Scalability, Usability, Reliability), then alphabetically by title within category, assign sequential 4-digit numbers starting from 0001
4. ASM-NNNN IDs: Sort alphabetically by assumption text, assign sequential numbers
5. OQ-NNNN IDs: Sort alphabetically by question text, assign sequential numbers
6. Functional areas listed in alphabetical order
7. Requirements within each functional area listed by REQ-NNNN order
8. No timestamps in artifact body
9. Sections must appear in template order
10. Priority summary table appears before detailed requirements

## Handling Edge Cases

### Too Many Requirements
If decomposition yields more than 25 REQs:
- Re-evaluate functional area boundaries — some areas may need merging
- Check if P2 items are truly requirements or just ideas
- Consider splitting into multiple phases with separate REQUIREMENTS.md per phase
- Document the scoping decision in the Assumptions section

### Conflicting Requirements
If two requirements contradict each other:
- Document the conflict as an Open Question (OQ-NNNN)
- Assign both requirements a temporary priority
- Flag for stakeholder resolution
- Do NOT silently resolve the conflict by dropping one requirement

### Missing Information
If the problem brief has open questions that block requirements:
- Create placeholder requirements marked with "[BLOCKED: OQ-NNNN]" in the description
- Assign priority P2 until the blocking question is resolved
- Document the dependency in the Open Questions section

### Requirements That Cross Functional Areas
If a requirement spans multiple functional areas:
- Assign it to the primary functional area
- Add a note in the description: "Cross-cuts: [Other Area Name]"
- Ensure user stories cover both areas

## Cross-Referencing

The REQUIREMENTS.md artifact is referenced by:
- **FUNCTIONAL_SPEC.md**: Each feature spec (FS-NNNN) maps to one or more REQ-NNNN
- **ARCHITECTURE.md**: Components are designed to fulfill REQ groups
- **TASKS.md**: Tasks trace back to REQs through feature specs
- **IMPLEMENTATION_PLAN.md**: Sprints are organized around REQ priorities
- **VIABILITY.md**: Cost estimates reference REQ complexity

## Quality Checklist

Before completing, verify:
- [ ] Problem brief has been fully analyzed (all SM, CON, NG referenced)
- [ ] Every success metric maps to at least one requirement
- [ ] Requirements do not contradict constraints
- [ ] Requirements do not overlap with non-goals
- [ ] Every REQ has a clear, testable acceptance criteria set
- [ ] Every REQ has at least one user story
- [ ] P0 REQs have 2-3 user stories
- [ ] User stories use Given/When/Then format
- [ ] All five NFR categories are covered
- [ ] NFRs have measurable metrics and measurement methods
- [ ] All IDs are sequential and deterministically ordered
- [ ] Dependency graph has no cycles
- [ ] Priority distribution is balanced (aim for 30% P0, 40% P1, 30% P2)
- [ ] Traceability matrix is complete
- [ ] Functional areas are logically grouped
- [ ] Artifact follows the standard template structure

## Common Pitfalls

1. **Everything is P0**: If more than 40% of requirements are P0, re-evaluate. True must-haves for an MVP are typically 3-7 requirements.
2. **User stories without acceptance criteria**: Every story must have at least one Given/When/Then criterion. Without it, the story is untestable.
3. **NFRs without metrics**: "The system should be fast" is not an NFR. "API response time p95 < 200ms under 500 concurrent users" is an NFR.
4. **Orphaned requirements**: Every REQ must trace back to the problem brief. If it does not support a success metric or address a user need, it does not belong.
5. **Circular dependencies**: REQ-0001 depends on REQ-0002 which depends on REQ-0001. This must be resolved before proceeding.
6. **Missing security NFRs**: Security is never optional. Even simple applications need authentication, authorization, and data protection requirements.
7. **Confusing requirements with implementation**: "Use React for the frontend" is an implementation decision, not a requirement. "Users must be able to access the system via web browser" is a requirement.
8. **Stories too large**: If a user story cannot be completed in a single sprint, it needs to be split into smaller stories.