/prd - Product Requirements Document

Transform product ideas into structured, implementable PRDs with user stories, acceptance criteria, and issue decomposition - bridging the gap between stakeholder intent and developer action.

Target: $ARGUMENTS

When to Use

• Translating a vague feature request into actionable requirements
• Starting a new feature that needs stakeholder alignment
• Converting user feedback into development tasks
• When @product or @analyst needs a structured output format
• Before /plan for features that need formal requirements
• NOT for: bug fixes (use /debug)
• NOT for: technical tasks with clear specs (use /plan directly)
• NOT for: exploratory ideation (use /brainstorm first)

Workflow

Step 1: Problem & Scope Definition

1. Identify the problem statement - What pain point does this solve?
2. Define target users - Primary and secondary personas
3. Establish success criteria - Measurable outcomes (not vague goals)
4. Set scope boundaries - Explicit in-scope and out-of-scope items
5. Scan existing codebase for related features:

# Find related modules, components, services
grep -rl "$KEYWORD" src/ --include="*.ts" --include="*.tsx" --include="*.vue" --include="*.svelte" 2>/dev/null | head -20

Output:

## 1. Problem & Scope

**Problem:** [Clear problem statement with evidence]
**Users:** [Primary: ..., Secondary: ...]
**Success Criteria:**
- [ ] [Measurable outcome 1]
- [ ] [Measurable outcome 2]
**In Scope:** [what's included]
**Out of Scope:** [what's explicitly excluded]
**Existing Code:** [related modules found in codebase]

BLOCKED until problem statement is clear and measurable.

Step 2: User Stories & Acceptance Criteria

1. Write user stories in standard format with Gherkin acceptance criteria
2. Cover all personas identified in Step 1
3. Include edge cases - What happens when things go wrong?
4. Prioritize stories using MoSCoW (Must/Should/Could/Won't)

For each story:

### US-[N]: [Story Title]

**As a** [persona],
**I want** [action],
**So that** [benefit].

**Priority:** Must Have | Should Have | Could Have | Won't Have

**Acceptance Criteria:**
```gherkin
GIVEN [precondition]
WHEN [action]
THEN [expected result]

GIVEN [precondition]
WHEN [error condition]
THEN [error handling]

**BLOCKED** until at least 3 user stories with Gherkin criteria exist.

### Step 3: Requirements Matrix

1. **Functional requirements** - What the system must do
2. **Non-functional requirements** - Performance, security, accessibility, i18n
3. **Technical constraints** - Stack, infrastructure, API compatibility
4. **Dependencies** - External services, other teams, data sources

**Output:**
```markdown
## 3. Requirements Matrix

### Functional
| ID | Requirement | Priority | Story |
|----|------------|----------|-------|
| FR-1 | [requirement] | Must | US-1 |

### Non-Functional
| ID | Requirement | Target | Measurement |
|----|------------|--------|-------------|
| NFR-1 | Response time | < 200ms p95 | Load test |
| NFR-2 | Accessibility | WCAG AA | Axe audit |

### Constraints
- [Technical constraint 1]
- [Infrastructure constraint]

### Dependencies
- [External service/team]

Step 4: Technical Feasibility Scan

1. Scan codebase for reusable patterns:

# Identify existing patterns, services, utilities
find src/ -type f -name "*.ts" -o -name "*.tsx" | head -50
# Check for existing API routes
find src/ -path "*/api/*" -name "*.ts" 2>/dev/null | head -20
# Check for existing types/interfaces
grep -rn "interface\|type " src/types/ 2>/dev/null | head -20

2. Identify integration points - What existing code touches this feature?
3. Estimate new infrastructure - New tables, APIs, services, queues needed
4. Flag risks - Breaking changes, migration needs, data concerns

Output:

## 4. Technical Feasibility

**Reusable:** [existing modules/patterns to leverage]
**New infrastructure:** [tables, APIs, services needed]
**Integration points:** [existing code that needs changes]
**Risks:** [breaking changes, migrations, data concerns]

Step 5: Issue Decomposition

1. Break PRD into implementable issues - Each issue is a single PR
2. Estimate size - S (< 2h), M (2-4h), L (4-8h), XL (> 8h, split further)
3. Map dependencies - Which issues block others?
4. Suggest agent assignments - Which specialist agent handles each issue?

Output:

## 5. Issue Breakdown

| # | Issue Title | Size | Depends On | Agent |
|---|------------|------|------------|-------|
| 1 | Create [model/schema] | S | - | @data |
| 2 | Implement [API endpoint] | M | #1 | @api |
| 3 | Build [UI component] | M | #2 | @builder |
| 4 | Add [tests] | M | #3 | @tester |
| 5 | Add [observability] | S | #2 | @builder |

**Critical Path:** #1 → #2 → #3 → #4
**Parallelizable:** #5 can run alongside #3-#4

Step 6: PRD Document Generation

1. Compile all sections into a single document
2. Write to file: docs/PRD-[feature-name].md
3. Include metadata: date, author, version, status (Draft/Review/Approved)

Step 7 (Optional): GitHub Issue Creation

If the user requests it, create issues:

# Create issues from the breakdown
gh issue create --title "[Issue Title]" --body "[Description with acceptance criteria]" --label "feature,[size]"

Verification Protocol

Before claiming the PRD is complete:

1. Problem statement exists with measurable success criteria
2. At least 3 user stories with Gherkin acceptance criteria
3. Non-functional requirements have measurable targets (not "fast" but "< 200ms")
4. Codebase scan was performed - reusable code identified
5. Issue breakdown exists with size estimates and dependencies
6. Every Must Have story maps to at least one issue
7. PRD file was written to docs/PRD-[name].md
8. No vague terms remain - all clarified with specifics

Anti-Rationalization

Rules

1. Problem before solution - Never write user stories without a clear problem statement
2. Measurable criteria only - Every success metric and NFR must have a number
3. Gherkin is mandatory - Every user story gets GIVEN/WHEN/THEN acceptance criteria
4. Codebase grounded - Scan existing code before proposing new infrastructure
5. Issues must be PR-sized - Any XL issue must be split further
6. MoSCoW prioritization - Every story gets a priority, no "everything is Must Have"
7. Dependencies explicit - Every issue lists what it blocks and what blocks it
8. Agent-ready - Each issue suggests which specialist agent should handle it

Output

──── /prd ────
Feature: $ARGUMENTS

Problem: [1-line problem statement]
Users: [primary persona]
Stories: [N] (Must: X, Should: Y, Could: Z)

Requirements:
  Functional: N
  Non-Functional: N
  Constraints: N

Issues: N (S: X, M: Y, L: Z)
Critical Path: [issue chain]

PRD saved: docs/PRD-[name].md
Issues created: [N] (if requested)

──── Ready for /plan ────