prd

/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

Excuse	Reality
"Requirements are in my head"	Unwritten requirements become misunderstood requirements. Write them down. Memory is not documentation.
"We can figure out scope during development"	Scope creep costs 3-10x more than upfront definition. Define it now.
"User stories are too formal"	Stories are negotiable contracts, not bureaucracy. They prevent the rework that comes from verbal specs.
"The PRD will be outdated immediately"	A living document beats no document. Update as you learn. Outdated > nonexistent.
"Just tell the developer what to build"	Developers need acceptance criteria, not verbal instructions that get lost between Slack messages.
"NFRs are obvious, we don't need to write them"	"Fast" means 50ms to one person and 2s to another. Write the number.
"We'll add acceptance criteria later"	Criteria written after implementation are just documentation, not specifications. Write them first.

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 ────