PRD Authoring Skill

Purpose

Manage early-stage project planning and requirements definition before entering the spec-driven development workflow. This skill integrates BMAD methodology's Product Manager and Business Analyst workflows to guide users from vague project ideas to well-defined Product Requirements Documents (PRDs) with clear success criteria, validated requirements, and actionable epic breakdowns.

The prd-authoring skill bridges the gap between "we have an idea" and "we're ready to write specs." It ensures that projects begin with:

• Clear problem statements and value propositions
• Data-driven market research and competitive analysis
• Specific, measurable, and testable requirements
• Well-defined success criteria and acceptance criteria
• Epic decomposition ready for sprint planning

PRDs created with this skill serve as strategic documents that can span multiple specs and persist across implementation iterations.

When to Use

Use this skill in the following situations:

• Starting a new project from an initial concept or idea
• Creating a product brief to formalize a vague project vision
• Conducting market research and competitive analysis
• Writing a comprehensive PRD with requirements and success criteria
• Validating an existing PRD against quality standards
• Breaking down a PRD into epics for sprint planning
• Preparing to transition from planning to the spec-authoring workflow
• Assessing project readiness and determining next steps

Do NOT use this skill for:

• Implementation-level specifications (use spec-authoring instead)
• Sprint planning from approved specs (use sprint-planner instead)
• Code implementation tasks (use issue-executor instead)

Prerequisites

• Project initialized with SynthesisFlow structure (docs/ directory exists)
• Basic understanding of product requirements and success criteria
• Stakeholder alignment on project goals (or willingness to develop it)

Optional but helpful:

• Market research or competitive analysis data
• User personas or target audience information
• Business objectives and constraints

PRD Philosophy

Strategy Before Tactics: PRDs define WHAT we're building and WHY before specs define HOW we'll build it.

Benefits:

• Stakeholder alignment: Ensure everyone agrees on goals before development
• Informed decisions: Base requirements on research and data, not assumptions
• Clear success metrics: Know what "done" looks like before starting
• Reduced waste: Catch misalignment early when changes are cheap
• Traceability: Link all specs and tasks back to business objectives

Workflow:

1. Initial idea or concept identified
2. Product brief created (problem, solution, users, value)
3. Market research conducted (competitors, landscape, opportunities)
4. PRD created (objectives, requirements, constraints, assumptions)
5. PRD validated against quality standards
6. Epic decomposition prepares transition to development
7. Specs created from epics (via spec-authoring workflow)

Workflow Commands

The status Command

Purpose

Assess project readiness and provide guidance on next workflow steps. This is the recommended starting point for any new project or when you're unsure what to do next.

Workflow

Step 1: Run Status Assessment

Execute the status check to understand current project state:

bash scripts/prd-authoring.sh status [project-name]

If no project name is provided, the script checks for any existing PRD work in docs/prds/.

Step 2: Review Status Report

The status command analyzes:

• Existence of docs/prds/ directory structure
• Presence of product brief document
• Presence of research document
• Presence of PRD document
• Completeness of each document (required sections present)

Output example:

=== PRD Status Report ===
Project: payment-gateway

Status: Research Phase
- ✓ Product brief exists (docs/prds/payment-gateway/product-brief.md)
- ✓ Brief is complete (all required sections present)
- ✗ Research document missing
- ✗ PRD not yet created

Recommendation: Run 'research' command to conduct market analysis
Next command: bash scripts/prd-authoring.sh research payment-gateway

Step 3: Follow Recommendations

Based on the status report, proceed with the recommended command. Common workflows:

• No brief exists: Run brief command first
• Brief exists, no research: Run research command
• Brief and research exist: Run create-prd command
• PRD exists but incomplete: Edit PRD or run validate-prd for specific issues
• PRD complete and validated: Run decompose command to create epics

Error Handling

No docs directory:

• Run project-init skill first to set up SynthesisFlow structure
• Or manually create docs/prds/ directory

Multiple projects detected:

• Specify project name explicitly: bash scripts/prd-authoring.sh status project-name

Partial documents:

• Status report identifies missing sections
• Edit files to add missing content or re-run relevant command

---

The brief Command

Purpose

Create a formal product brief from an initial project concept. The product brief is a lightweight document that captures the core vision: what problem we're solving, for whom, and why it matters.

Workflow

Step 1: Gather Initial Information

Discuss with the user:

• What problem does this project solve?
• Who experiences this problem?
• What solution are we proposing?
• What value does this provide?
• How will we measure success?

Step 2: Run Brief Creation Script

Execute the script to create product brief structure:

bash scripts/prd-authoring.sh brief "Project Name"

This will:

• Convert project name to kebab-case (e.g., "Payment Gateway" → "payment-gateway")
• Create docs/prds/payment-gateway/ directory
• Create product-brief.md with YAML frontmatter and template sections

Step 3: Populate Product Brief

Work with the user to fill in the template sections:

---
title: Payment Gateway Integration
type: product-brief
status: draft
created: 2025-11-04
updated: 2025-11-04
---

# Product Brief: Payment Gateway Integration

## Problem Statement

Our e-commerce platform currently lacks payment processing capabilities,
forcing customers to complete purchases via manual invoice. This creates
friction in the buying process and reduces conversion rates.

## Target Users

- Online shoppers making purchases on our platform
- Merchants managing sales and refunds
- Finance team reconciling payments

## Proposed Solution

Integrate a third-party payment gateway (Stripe) to enable secure,
real-time payment processing with support for multiple payment methods.

## Value Proposition

- Customers: Seamless checkout experience with instant confirmation
- Business: Increased conversion rates, automated payment reconciliation
- Merchants: Simplified refund and chargeback management

## Success Metrics

- 80% reduction in checkout abandonment rate
- 95% of payments processed within 3 seconds
- Zero PCI compliance violations
- Support for 5+ payment methods by launch

Step 4: Review and Refine

Review the brief with stakeholders:

• Ensure problem statement is clear and specific
• Validate target users are well-defined
• Confirm value proposition is compelling
• Verify success metrics are measurable

Step 5: Save and Commit

Once the brief is complete:

git add docs/prds/payment-gateway/product-brief.md
git commit -m "docs: Add product brief for payment gateway"

Step 6: Check Status

Run status command to confirm brief is complete:

bash scripts/prd-authoring.sh status payment-gateway

Usage Example

Scenario: Starting a new analytics dashboard project

# Create product brief
bash scripts/prd-authoring.sh brief "Analytics Dashboard"

# Edit docs/prds/analytics-dashboard/product-brief.md
# Fill in problem, users, solution, value, metrics

# Verify completion
bash scripts/prd-authoring.sh status analytics-dashboard

Error Handling

Project directory already exists:

• Check if brief already created: ls docs/prds/project-name/
• Either use different name or edit existing brief
• Use status command to see what exists

Vague problem statement:

• Ask probing questions to get specifics
• What exactly is broken or missing?
• Who is affected and how often?
• What's the business impact?

Unmeasurable success metrics:

• Convert vague goals to specific numbers
• "Better performance" → "95th percentile response time < 200ms"
• "Improved UX" → "Task completion rate > 85%"

---

The research Command

Purpose

Guide users through market research and competitive analysis to inform PRD requirements with data-driven insights.

Workflow

Step 1: Verify Brief Exists

Check that product brief is complete:

bash scripts/prd-authoring.sh status project-name

If brief is missing or incomplete, complete it first before conducting research.

Step 2: Run Research Creation Script

Execute the script to create research document structure:

bash scripts/prd-authoring.sh research project-name

This creates docs/prds/project-name/research.md with template sections.

Step 3: Define Research Questions

Work with the user to identify key questions:

• Who are the main competitors in this space?
• What features do they offer?
• What are their strengths and weaknesses?
• What market opportunities exist?
• What do users say about existing solutions?
• What technical approaches do competitors use?

Step 4: Conduct Research

Guide the user through research activities:

Competitive Analysis:

• Identify 3-5 direct competitors
• Document their key features and pricing
• Note what they do well and poorly
• Identify gaps in their offerings

Market Analysis:

• Research market size and trends
• Identify target market segments
• Document regulatory or compliance requirements
• Note industry standards and best practices

User Research (if applicable):

• Review user feedback on competitor products
• Conduct user interviews or surveys
• Analyze support tickets or feature requests
• Document pain points and unmet needs

Step 5: Populate Research Document

Document findings in structured format:

---
title: Payment Gateway Research
type: research
status: complete
created: 2025-11-04
updated: 2025-11-04
---

# Research: Payment Gateway Integration

## Competitive Analysis

### Competitor 1: Stripe
- **Strengths**: Developer-friendly API, excellent documentation, 135+ currencies
- **Weaknesses**: Higher fees for international cards (3.9% + $0.30)
- **Key Features**: Recurring billing, fraud detection, mobile SDKs
- **Market Position**: Leader in developer-focused payment processing

### Competitor 2: PayPal
- **Strengths**: Brand recognition, buyer protection, wide adoption
- **Weaknesses**: Higher dispute rates, complex API
- **Key Features**: PayPal checkout, Venmo integration, buyer credit
- **Market Position**: Consumer-focused, trusted brand

### Competitor 3: Square
- **Strengths**: Unified POS and online payments, simple pricing
- **Weaknesses**: Limited international support, fewer currencies
- **Key Features**: In-person + online, inventory management, analytics
- **Market Position**: Small business focus, retail-oriented

## Market Insights

- Payment processing market growing 12% annually
- Mobile payments expected to reach 60% of e-commerce by 2026
- PCI DSS 4.0 compliance required by March 2025
- Buy-now-pay-later (BNPL) options increasing in demand

## User Feedback Analysis

Common pain points with existing solutions:
- Complex integration requiring weeks of development
- Hidden fees and confusing pricing structures
- Poor error messages during failed transactions
- Lack of real-time reconciliation with accounting systems

Desired features:
- One-click checkout experience
- Multiple payment method support (cards, wallets, BNPL)
- Instant refund processing
- Detailed transaction analytics

## Technical Considerations

- REST API vs SDK integration trade-offs
- Webhook reliability for async event handling
- PCI compliance scope (SAQ-A vs SAQ-A-EP)
- Tokenization for recurring payments
- 3D Secure 2.0 for fraud prevention

## Recommendations

1. **Choose Stripe**: Best developer experience, comprehensive features
2. **Priority features**: Card payments, Apple Pay, Google Pay
3. **Phase 2**: Add BNPL options (Klarna, Affirm)
4. **Compliance**: Implement SAQ-A eligible integration (no card data storage)

Step 6: Extract Key Insights

Summarize findings that will inform PRD:

• Which features are table stakes vs differentiators?
• What technical approaches are proven?
• What user needs are unmet by competitors?
• What constraints exist (compliance, budget, timeline)?

Step 7: Review and Commit

git add docs/prds/project-name/research.md
git commit -m "docs: Add market research for project-name"

# Verify research is complete
bash scripts/prd-authoring.sh status project-name

Usage Example

Scenario: Researching real-time notification system

# Create research document
bash scripts/prd-authoring.sh research notification-system

# Conduct analysis
# - Compare Firebase, Pusher, Ably, custom WebSocket
# - Review scalability and cost at different volumes
# - Document latency requirements from user research

# Document findings in docs/prds/notification-system/research.md

# Verify completion
bash scripts/prd-authoring.sh status notification-system

Error Handling

Brief doesn't exist yet:

• Complete product brief first
• Research should be informed by brief's problem statement

Research is too broad:

• Focus on questions that impact requirements
• Avoid analysis paralysis - perfect is the enemy of done
• Time-box research activities (e.g., 4 hours max)

No clear competitors:

• Research adjacent solutions or alternative approaches
• Document why no direct competitors exist
• Analyze components that could be assembled

Conflicting data sources:

• Document multiple perspectives
• Note confidence levels in findings
• Prioritize primary research over secondary

---

The create-prd Command

Purpose

Generate a comprehensive Product Requirements Document from product brief and research findings. The PRD is the authoritative definition of what will be built and how success will be measured.

Workflow

Step 1: Verify Prerequisites

Check that brief and research are complete:

bash scripts/prd-authoring.sh status project-name

Both documents should exist and be marked complete before creating PRD.

Step 2: Run PRD Creation Script

Execute the script to create PRD structure:

bash scripts/prd-authoring.sh create-prd project-name

This creates docs/prds/project-name/prd.md with comprehensive template sections.

Step 3: Define Objectives

Work with the user to articulate clear project objectives:

Good objectives are:

• Specific: Clearly state what will be achieved
• Measurable: Include quantifiable targets
• Achievable: Realistic given constraints
• Relevant: Aligned with business goals
• Time-bound: Have clear deadlines

Example:

## Objectives

### Primary Objectives

1. **Enable online payment processing**
   - Support credit/debit card payments with PCI compliance
   - Process payments in under 3 seconds (95th percentile)
   - Launch by Q2 2026

2. **Increase conversion rates**
   - Reduce checkout abandonment from 45% to 15%
   - Support 5+ payment methods by launch
   - Enable one-click checkout for returning customers

3. **Automate payment reconciliation**
   - Eliminate manual invoice processing
   - Real-time sync with accounting system
   - Reduce finance team reconciliation time by 80%

### Secondary Objectives

1. Enable subscription and recurring billing (Phase 2)
2. Support international currencies (Phase 2)
3. Provide merchant analytics dashboard (Phase 3)

Step 4: Define Success Criteria

Specify measurable criteria that indicate project success:

## Success Criteria

### Launch Criteria (Must-Have)

- [ ] Successfully process 100 test transactions with 0% failure rate
- [ ] PCI DSS compliance validation passed (SAQ-A)
- [ ] Checkout flow completion time < 60 seconds (90th percentile)
- [ ] Support Visa, Mastercard, American Express, Apple Pay, Google Pay
- [ ] 99.9% payment processing uptime over 30-day period

### Success Metrics (3 Months Post-Launch)

- [ ] 10,000+ successful transactions processed
- [ ] Checkout abandonment rate < 20% (vs 45% baseline)
- [ ] Average payment processing time < 2.5 seconds
- [ ] Customer satisfaction score > 4.5/5 for checkout experience
- [ ] Zero security incidents or PCI compliance violations
- [ ] 90% reduction in manual payment reconciliation time

### Stretch Goals

- [ ] Checkout abandonment < 15%
- [ ] Support 10+ payment methods
- [ ] Process 50,000+ transactions per month

Step 5: Document Functional Requirements

List specific, testable functional requirements:

## Functional Requirements

### FR1: Payment Processing
- **Description**: Process credit/debit card payments securely
- **Inputs**: Card details, payment amount, customer info
- **Outputs**: Transaction confirmation, receipt
- **Acceptance Criteria**:
  - Accepts Visa, Mastercard, American Express, Discover
  - Validates card details before submission
  - Returns clear error messages for failed transactions
  - Generates unique transaction ID for each payment
  - Sends confirmation email within 30 seconds

### FR2: Payment Method Management
- **Description**: Support multiple payment methods
- **Inputs**: Customer payment method preferences
- **Outputs**: Saved payment methods, default selection
- **Acceptance Criteria**:
  - Customers can save multiple payment methods
  - Supports cards, Apple Pay, Google Pay
  - Allows setting default payment method
  - Enables payment method deletion
  - Tokenizes card data (no raw card storage)

### FR3: Refund Processing
- **Description**: Enable full and partial refunds
- **Inputs**: Original transaction ID, refund amount
- **Outputs**: Refund confirmation, updated transaction status
- **Acceptance Criteria**:
  - Merchants can issue refunds within 90 days
  - Supports partial refunds
  - Refunds process within 5-7 business days
  - Customer receives refund notification
  - Accounting system updated automatically

Step 6: Document Non-Functional Requirements

Specify quality attributes and constraints:

## Non-Functional Requirements

### NFR1: Performance
- Payment processing response time < 3 seconds (95th percentile)
- Checkout page load time < 2 seconds
- Support 1000 concurrent transactions
- 99.9% uptime SLA

### NFR2: Security
- PCI DSS Level 1 compliance
- TLS 1.3 for all payment data transmission
- Tokenization of card data (no storage of card numbers)
- 3D Secure 2.0 for fraud prevention
- Regular security audits and penetration testing

### NFR3: Reliability
- Automatic retry for transient failures
- Graceful degradation if payment gateway is down
- Transaction logging for audit trail
- Daily backups of transaction data

### NFR4: Usability
- Checkout flow completable in < 5 steps
- Mobile-responsive design
- WCAG 2.1 AA accessibility compliance
- Support for 10+ languages

### NFR5: Scalability
- Handle 10x traffic during peak shopping periods
- Horizontal scaling for increased load
- Database optimization for transaction queries

Step 7: Document Constraints and Assumptions

Be explicit about limitations and dependencies:

## Constraints

- Must use Stripe as payment provider (existing contract)
- Cannot store raw credit card numbers (PCI compliance)
- Must integrate with existing Salesforce CRM
- Launch deadline: June 30, 2026 (non-negotiable)
- Budget: $150k for development and first year operational costs

## Assumptions

- Average transaction value: $75
- Expected transaction volume: 5,000/month initially
- Users have modern browsers (last 2 versions)
- Finance team will handle chargebacks manually
- Stripe API will maintain backward compatibility
- Customer support will handle payment-related inquiries

Step 8: Define Out of Scope

Clearly state what will NOT be included:

## Out of Scope (For This Phase)

- Cryptocurrency payments
- Subscription/recurring billing (deferred to Phase 2)
- International currencies beyond USD (Phase 2)
- In-person/POS payment processing
- Custom payment gateway integration
- Buy-now-pay-later (BNPL) options (Phase 2)
- Merchant analytics dashboard (Phase 3)

Step 9: Review and Refine

Review the complete PRD with stakeholders:

• Are objectives clear and measurable?
• Are requirements specific and testable?
• Are success criteria appropriate?
• Are constraints and assumptions documented?
• Is scope well-defined?

Step 10: Save and Commit

git add docs/prds/project-name/prd.md
git commit -m "docs: Add PRD for project-name"

# Check status
bash scripts/prd-authoring.sh status project-name

Usage Example

Scenario: Creating PRD for mobile app authentication

# Verify prerequisites
bash scripts/prd-authoring.sh status mobile-auth

# Create PRD structure
bash scripts/prd-authoring.sh create-prd mobile-auth

# Populate PRD with:
# - Objectives: Enable secure mobile login
# - Success Criteria: 99.9% auth success rate, <2s login time
# - Functional Requirements: Biometric auth, 2FA, password reset
# - Non-Functional Requirements: Security (OAuth 2.0), Performance
# - Constraints: Must support iOS 15+ and Android 10+

# Commit completed PRD
git add docs/prds/mobile-auth/prd.md
git commit -m "docs: Add PRD for mobile authentication"

Error Handling

Brief or research missing:

• Complete prerequisites first
• Use status command to identify what's missing
• PRD quality depends on foundation work

Requirements are too vague:

• Make requirements specific and measurable
• Add clear acceptance criteria for each requirement
• Ask: "How would we test this?"

Scope is too large:

• Break into phases (MVP, Phase 2, Phase 3)
• Define clear out-of-scope items
• Focus on core value proposition first

Success criteria not measurable:

• Convert qualitative goals to quantitative metrics
• "Better UX" → "Task completion rate > 85%"
• "Fast performance" → "P95 response time < 200ms"

Conflicting requirements:

• Document the conflict explicitly
• Escalate to stakeholders for prioritization
• Note decision rationale in PRD

---

The validate-prd Command

Purpose

Validate PRD quality against standards and best practices. Catches common issues like missing sections, vague requirements, and unmeasurable success criteria.

Workflow

Step 1: Run Validation Script

Execute the validation check:

bash scripts/prd-authoring.sh validate-prd project-name

Step 2: Review Validation Report

The script checks for:

Completeness:

• YAML frontmatter present with required fields
• Objectives section exists and non-empty
• Success criteria section exists with measurable items
• Functional requirements section exists
• Non-functional requirements section exists
• Constraints section exists
• Assumptions section exists

Quality Checks:

• Requirements are specific (not vague language like "should", "might", "probably")
• Success criteria are measurable (include numbers/percentages)
• Acceptance criteria defined for each requirement
• No ambiguous terms ("fast", "good", "better" without quantification)
• Out of scope section clarifies boundaries

SMART Criteria (for objectives and requirements):

• Specific: Clearly defined, not vague
• Measurable: Quantifiable success metrics
• Achievable: Realistic given constraints
• Relevant: Aligned with business goals
• Time-bound: Has clear deadlines

Output example:

=== PRD Validation Report ===
Project: payment-gateway
File: docs/prds/payment-gateway/prd.md

Completeness: 8/8 ✓
- ✓ YAML frontmatter present
- ✓ Objectives section (3 objectives defined)
- ✓ Success criteria section (12 criteria, 10 measurable)
- ✓ Functional requirements (8 requirements)
- ✓ Non-functional requirements (5 requirements)
- ✓ Constraints (5 constraints documented)
- ✓ Assumptions (6 assumptions documented)
- ✓ Out of scope (7 items excluded)

Quality Issues: 3
⚠ Line 45: Success criterion lacks measurement - "improve user experience"
  Suggestion: Specify measurable UX metric (e.g., "task completion rate > 85%")

⚠ Line 67: Vague language in FR3 - "reasonable time"
  Suggestion: Define specific time threshold (e.g., "within 5 seconds")

⚠ Line 89: Ambiguous requirement - "should support most payment methods"
  Suggestion: List specific payment methods required

Recommendations:
1. Quantify vague success criteria
2. Replace ambiguous terms with specific values
3. Add acceptance criteria to FR5 and FR6

Overall: GOOD (Minor revisions recommended)

Step 3: Address Issues

For each issue identified:

1. Locate the line number in the PRD
2. Understand the specific problem
3. Revise the content to address the issue
4. Re-run validation to confirm fix

Common fixes:

• "Improve performance" → "Reduce P95 response time to <200ms"
• "Support many users" → "Support 10,000 concurrent users"
• "Should work well" → "Must achieve 99.9% uptime"

Step 4: Re-validate

After making changes, run validation again:

bash scripts/prd-authoring.sh validate-prd project-name

Continue iterating until validation passes with no critical issues.

Step 5: Commit Validated PRD

Once validation passes:

git add docs/prds/project-name/prd.md
git commit -m "docs: Validate and refine PRD for project-name"

Validation Modes

Strict Mode (default):

• Flags any vague or ambiguous language
• Requires all sections present
• Enforces SMART criteria strictly

Lenient Mode:

• Allows some sections to be optional (for early drafts)
• Warnings instead of errors for minor issues
• Useful during initial PRD creation

To use lenient mode:

bash scripts/prd-authoring.sh validate-prd project-name --lenient

Usage Example

Scenario: Validating API redesign PRD

# Run validation
bash scripts/prd-authoring.sh validate-prd api-redesign

# Review issues:
# - Missing success criteria for performance objectives
# - Vague requirement: "should be fast"
# - No acceptance criteria for FR7

# Edit docs/prds/api-redesign/prd.md to fix issues

# Re-validate
bash scripts/prd-authoring.sh validate-prd api-redesign

# Validation passes ✓

Error Handling

PRD file doesn't exist:

• Run create-prd command first
• Check project name spelling
• Use status command to confirm PRD location

Too many validation errors:

• Use lenient mode during drafting
• Focus on completing content first, polish later
• Address critical issues before minor ones

False positives:

• Some domain-specific terms may be flagged incorrectly
• Document rationale in PRD if intentionally using flagged term
• Validation is a guide, not absolute law

Requirements conflict with constraints:

• Validation may flag logical conflicts
• Review with stakeholders to resolve
• Update either requirements or constraints

---

The decompose Command

Purpose

Break down a validated PRD into epics for sprint planning. Epics are independently deliverable units of work that align with PRD objectives and can be further broken down into user stories during sprint planning.

Workflow

Step 1: Validate PRD First

Ensure PRD passes validation:

bash scripts/prd-authoring.sh validate-prd project-name

Only decompose validated PRDs to ensure quality input.

Step 2: Run Decomposition Script

Execute the epic decomposition:

bash scripts/prd-authoring.sh decompose project-name

This creates docs/prds/project-name/epics.md with epic breakdown.

Step 3: Identify Epic Boundaries

Work with the user to group requirements into logical epics:

Epic Definition Criteria:

• Independently deliverable (provides value on its own)
• Aligns with one or more PRD objectives
• Can be completed in 2-4 sprints
• Has clear scope boundaries
• Minimal dependencies on other epics (where possible)

Common Epic Patterns:

• By user flow (e.g., "User Registration Epic", "Checkout Epic")
• By technical layer (e.g., "API Development Epic", "UI Epic")
• By component (e.g., "Payment Processing Epic", "Notification Epic")
• By phase (e.g., "MVP Epic", "Phase 2 Features Epic")

Step 4: Define Each Epic

For each epic, document:

---
title: Payment Gateway Epics
type: epic-breakdown
prd: docs/prds/payment-gateway/prd.md
status: draft
created: 2025-11-04
updated: 2025-11-04
---

# Epic Breakdown: Payment Gateway

## Epic 1: Payment Processing Core

**Objective**: Enable basic credit/debit card payment processing

**Scope**:
- Integrate Stripe SDK
- Implement payment form with card input
- Process payment transactions
- Handle success/failure responses
- Generate transaction receipts

**Requirements Coverage**:
- FR1: Payment Processing (100%)
- NFR1: Performance (payment processing time)
- NFR2: Security (TLS, tokenization)

**Success Criteria**:
- Process 100 test transactions with 0% failure
- P95 processing time < 3 seconds
- PCI SAQ-A compliance validated

**Dependencies**:
- None (foundational epic)

**Estimated Effort**: 3 sprints

**Out of Scope**:
- Refund processing (Epic 3)
- Multiple payment methods (Epic 2)
- Subscription billing (Phase 2)

---

## Epic 2: Payment Methods

**Objective**: Support multiple payment methods (Apple Pay, Google Pay)

**Scope**:
- Integrate Apple Pay SDK
- Integrate Google Pay SDK
- Add payment method selection UI
- Save payment methods for returning customers
- Set default payment method

**Requirements Coverage**:
- FR2: Payment Method Management (100%)
- NFR4: Usability (checkout flow simplicity)

**Success Criteria**:
- Support 5+ payment methods by launch
- One-click checkout for returning customers
- Payment method save rate > 60%

**Dependencies**:
- Epic 1 (Payment Processing Core) must be complete

**Estimated Effort**: 2 sprints

**Out of Scope**:
- Cryptocurrency payments
- BNPL options (Phase 2)

---

## Epic 3: Refunds and Reconciliation

**Objective**: Enable refund processing and accounting integration

**Scope**:
- Implement full and partial refund flows
- Integrate with accounting system (Salesforce)
- Real-time transaction sync
- Automated reconciliation reporting
- Refund notification emails

**Requirements Coverage**:
- FR3: Refund Processing (100%)
- Objective 3: Automate payment reconciliation

**Success Criteria**:
- Refunds process within 5-7 business days
- 100% transaction sync accuracy
- 80% reduction in manual reconciliation time

**Dependencies**:
- Epic 1 (Payment Processing Core) must be complete

**Estimated Effort**: 2 sprints

**Out of Scope**:
- Chargeback handling (manual process)
- Dispute management (Phase 2)

---

## Epic 4: Security and Compliance

**Objective**: Achieve PCI DSS compliance and implement fraud prevention

**Scope**:
- Implement 3D Secure 2.0
- Complete PCI DSS self-assessment (SAQ-A)
- Set up transaction logging and audit trails
- Implement fraud detection rules
- Security audit and penetration testing

**Requirements Coverage**:
- NFR2: Security (100%)
- NFR3: Reliability (transaction logging)

**Success Criteria**:
- PCI DSS compliance certification
- Zero security incidents post-launch
- Fraud detection blocks 95%+ of suspicious transactions

**Dependencies**:
- Epic 1 (Payment Processing Core) - security built on top

**Estimated Effort**: 2 sprints

**Out of Scope**:
- Advanced fraud ML models (Phase 2)
- Biometric authentication (future)

Step 5: Map Epic Dependencies

Create dependency graph:

## Epic Dependencies

Epic 1: Payment Processing Core (Foundational) │ ├─→ Epic 2: Payment Methods (Depends on Epic 1) ├─→ Epic 3: Refunds and Reconciliation (Depends on Epic 1) └─→ Epic 4: Security and Compliance (Depends on Epic 1)

Recommended Sequence:

1. Epic 1 (Sprint 1-3)
2. Epic 4 in parallel with Epic 1 sprints 2-3 (Sprint 2-4)
3. Epic 2 and Epic 3 can proceed in parallel (Sprint 4-6)

Step 6: Verify Coverage

Ensure all PRD requirements are covered by at least one epic:

## Requirements Traceability

| Requirement | Epic(s) | Coverage |
|-------------|---------|----------|
| FR1: Payment Processing | Epic 1 | 100% |
| FR2: Payment Method Management | Epic 2 | 100% |
| FR3: Refund Processing | Epic 3 | 100% |
| NFR1: Performance | Epic 1 | 100% |
| NFR2: Security | Epic 4 | 100% |
| NFR3: Reliability | Epic 3, Epic 4 | 100% |
| NFR4: Usability | Epic 2 | 100% |
| NFR5: Scalability | Epic 1 | 100% |

Total Coverage: 100% ✓

Step 7: Review and Commit

Review epic breakdown with stakeholders:

• Are epics independently deliverable?
• Are dependencies realistic?
• Is effort estimation reasonable?
• Does sequence make sense?

Commit the epic breakdown:

git add docs/prds/project-name/epics.md
git commit -m "docs: Add epic decomposition for project-name"

Step 8: Transition to Spec Authoring

For each epic, optionally generate initial spec proposals:

bash scripts/prd-authoring.sh generate-specs project-name

This creates spec proposal structure in docs/changes/ for each epic:

docs/changes/payment-processing-core/
  ├── proposal.md      (Epic scope and objectives)
  ├── spec-delta.md    (Technical specifications)
  └── tasks.md         (Initial task breakdown)

Each spec proposal links back to the PRD and epic for traceability.

Usage Example

Scenario: Decomposing user management PRD

# Validate PRD first
bash scripts/prd-authoring.sh validate-prd user-management

# Decompose into epics
bash scripts/prd-authoring.sh decompose user-management

# Review generated epics:
# - Epic 1: User Registration and Login
# - Epic 2: Profile Management
# - Epic 3: Role-Based Access Control
# - Epic 4: Audit and Compliance

# Verify coverage and dependencies
# Edit docs/prds/user-management/epics.md if needed

# Generate spec proposals
bash scripts/prd-authoring.sh generate-specs user-management

# Ready for spec-authoring workflow

Error Handling

PRD not validated:

• Run validate-prd first
• Fix validation issues before decomposition
• Quality input → quality output

Epic scope too large:

• Break down further into smaller epics
• Aim for 2-4 sprint delivery per epic
• Consider phased approach (MVP + enhancements)

Epic scope too small:

• Combine related epics
• Avoid over-fragmenting work
• Ensure each epic delivers standalone value

Circular dependencies:

• Review dependency graph
• Refactor epic boundaries if needed
• Some coupling may be unavoidable (document it)

Incomplete requirements coverage:

• Review traceability matrix
• Add missing epics for uncovered requirements
• Update PRD if requirements are truly out of scope

---

Integration with Other Skills

Transition to spec-authoring

After completing PRD decomposition:

1. Generate spec proposals from epics (optional):

   bash scripts/prd-authoring.sh generate-specs project-name
   

2. For each epic, use spec-authoring to create detailed specs:

   • Run bash scripts/spec-authoring.sh propose epic-name
   • Populate proposal.md with epic scope and objectives
   • Populate spec-delta.md with technical requirements
   • Populate tasks.md with implementation breakdown
   • Create Spec PR for review

3. Maintain traceability:

   • Link spec proposals back to PRD and epic
   • Reference PRD requirements in spec-delta.md
   • Ensure spec success criteria align with PRD success criteria

Example spec proposal linking to PRD:

# Proposal: Payment Processing Core

## Context

This spec implements **Epic 1: Payment Processing Core** from the
Payment Gateway PRD (docs/prds/payment-gateway/prd.md).

## PRD Requirements Covered

- FR1: Payment Processing
- NFR1: Performance (payment processing time < 3s)
- NFR2: Security (TLS, tokenization, PCI compliance)

## Success Criteria (from PRD)

- Process 100 test transactions with 0% failure
- P95 processing time < 3 seconds
- PCI SAQ-A compliance validated

[Rest of spec proposal...]

Integration with sprint-planner

After specs are approved:

1. Use sprint-planner to select approved specs for sprint
2. Epic structure from PRD informs sprint scope
3. PRD success criteria guide sprint goals

Integration with doc-indexer

PRD documents are indexed alongside specs:

# Doc-indexer includes PRD documents
bash scripts/doc-indexer.sh

# Output includes:
# - Product Briefs (docs/prds/*/product-brief.md)
# - Research Documents (docs/prds/*/research.md)
# - PRDs (docs/prds/*/prd.md)
# - Epic Breakdowns (docs/prds/*/epics.md)

Integration with project-init

When initializing new projects:

1. Project-init may suggest running prd-authoring for new projects
2. Creates docs/prds/ directory structure
3. Recommends starting with status command

---

Common Workflows

Greenfield Project (Idea to PRD)

Complete workflow for brand new project:

# 1. Assess starting point
bash scripts/prd-authoring.sh status

# 2. Create product brief
bash scripts/prd-authoring.sh brief "New Project"
# Edit docs/prds/new-project/product-brief.md

# 3. Conduct research
bash scripts/prd-authoring.sh research new-project
# Edit docs/prds/new-project/research.md

# 4. Create PRD
bash scripts/prd-authoring.sh create-prd new-project
# Edit docs/prds/new-project/prd.md

# 5. Validate PRD
bash scripts/prd-authoring.sh validate-prd new-project
# Fix any issues and re-validate

# 6. Decompose into epics
bash scripts/prd-authoring.sh decompose new-project
# Review docs/prds/new-project/epics.md

# 7. Generate spec proposals
bash scripts/prd-authoring.sh generate-specs new-project

# 8. Transition to spec-authoring for each epic

Brownfield Enhancement (Existing System)

Workflow for adding features to existing system:

# 1. Start with research (brief may be lightweight)
bash scripts/prd-authoring.sh brief "System Enhancement"
# Brief can reference existing system docs

bash scripts/prd-authoring.sh research system-enhancement
# Research focuses on gap analysis

# 2. Create focused PRD for enhancement
bash scripts/prd-authoring.sh create-prd system-enhancement
# PRD defines delta from current state

# 3. Validate and decompose
bash scripts/prd-authoring.sh validate-prd system-enhancement
bash scripts/prd-authoring.sh decompose system-enhancement

# 4. Proceed to spec-authoring

Skipping Steps (When Prerequisites Exist)

If some work already exists:

# Check what exists
bash scripts/prd-authoring.sh status project-name

# If research exists but no PRD, skip to create-prd
bash scripts/prd-authoring.sh create-prd project-name

# If PRD exists but needs validation
bash scripts/prd-authoring.sh validate-prd project-name

# If PRD validated, go straight to decompose
bash scripts/prd-authoring.sh decompose project-name

---

Error Handling and Troubleshooting

General Issues

docs/prds/ directory doesn't exist:

# Solution: Create directory structure
mkdir -p docs/prds
# Or run project-init if full structure needed

Permission denied when running scripts:

# Solution: Make script executable
chmod +x scripts/prd-authoring.sh

Script not found:

# Solution: Run from project root or use absolute path
cd /path/to/project
bash scripts/prd-authoring.sh status

Command-Specific Issues

brief: Product name conflicts with existing:

• Check ls docs/prds/ for existing projects
• Use different name or append version (e.g., "payment-gateway-v2")
• Or work with existing brief if intentional

research: Brief incomplete, can't proceed:

• Run status to identify missing brief sections
• Complete brief first, then return to research
• Research quality depends on brief clarity

create-prd: Prerequisites missing:

• Run status to see what's needed
• Brief and research should be complete first
• Can skip research for small projects, but not recommended

validate-prd: Too many errors to fix:

• Use lenient mode during drafting: --lenient flag
• Focus on content completeness first, polish later
• Address critical issues (missing sections) before minor ones

decompose: Requirements don't cluster into clear epics:

• Review PRD structure - may be too granular or too broad
• Try different epic boundaries (by user flow vs by component)
• Consult with architect or tech lead on technical decomposition
• It's okay to have some overlap between epics (document it)

Quality Issues

PRD requirements are still vague after validation:

• Validation catches patterns but can't ensure full clarity
• Review each requirement with stakeholder
• Ask: "How would we test this?" and "What does done look like?"
• Iterate with user to refine language

Success criteria not truly measurable:

• Convert qualitative to quantitative where possible
• For subjective measures, define evaluation method
• Example: "Intuitive UX" → "User testing shows 80% task success without help"

Epic dependencies are complex and blocking:

• This may indicate PRD scope is too ambitious
• Consider phasing: MVP with fewer dependencies first
• Document dependencies clearly and plan sprint sequence accordingly
• Some coupling is normal (just make it explicit)

Process Issues

Stakeholders disagree on objectives:

• PRD authoring surfaces alignment issues early (this is good!)
• Document competing perspectives in PRD
• Escalate to decision-maker for prioritization
• Update PRD to reflect final decision with rationale

Research is taking too long:

• Time-box research activities (e.g., 4-8 hours max)
• Focus on questions that impact requirements
• Perfect information is impossible - make best decision with available data
• Document confidence levels and assumptions

PRD keeps changing during validation:

• Some iteration is normal and healthy
• If excessive, may indicate unclear initial vision
• Lock PRD after 2-3 validation cycles and proceed
• Future changes can be versioned (e.g., prd-v2.md)

---

Best Practices

For Product Briefs

• Keep brief to 1-2 pages (lightweight document)
• Focus on "why" over "how"
• Make problem statement specific and evidence-based
• Define success metrics early (sets direction for PRD)

For Research

• Time-box research to prevent analysis paralysis
• Focus on actionable insights that inform requirements
• Document sources and confidence levels
• Prioritize primary research (user interviews) over secondary (articles)

For PRDs

• Requirements should be testable - ask "How would we verify this?"
• Success criteria should be measurable - include numbers
• Be explicit about constraints and assumptions
• Define "out of scope" to prevent scope creep
• Link requirements back to objectives (traceability)
• Version PRDs if substantial changes occur (prd-v2.md)

For Epic Decomposition

• Epics should deliver standalone value
• Aim for 2-4 sprints per epic (not too large)
• Minimize dependencies where possible
• Document dependencies clearly when unavoidable
• Ensure 100% requirements coverage (no orphans)
• Maintain traceability back to PRD

For Overall Process

• Don't skip steps - each builds on the previous
• Involve stakeholders early and often
• Document decisions and rationale
• Commit work incrementally (don't wait until perfect)
• Use validation to catch issues early
• Maintain traceability throughout workflow

---

Examples

Comprehensive examples are available in the skills/prd-authoring/examples/ directory:

Payment Gateway Integration Example

A complete, realistic example project showing the full PRD authoring workflow:

Project Overview:

• Problem: 45% cart abandonment due to manual invoice processing
• Solution: Integrate Stripe for real-time online payment processing
• Value: Recover $1.8M in lost revenue, save $100K in operational costs
• Timeline: 6 months to launch (Q2 2026)

Example Files:

1. Product Brief (01-product-brief-example.md)

   • Clear problem statement with quantified business impact
   • Well-defined user personas (Online Shopper Sarah, Sales Rep Mike)
   • Specific value propositions: 60s checkout vs 24-48h manual process
   • Measurable success metrics: 55% → 75% conversion rate

2. Research Document (02-research-example.md)

   • Competitive analysis: Stripe, PayPal/Braintree, Square
   • Market insights: $154B digital payment market, 14.2% CAGR
   • User feedback: 70% cite checkout complexity as pain point
   • Technical considerations: PCI compliance, fraud detection, APIs
   • Recommendation: Use Stripe for best developer experience

3. PRD - Abbreviated (03-prd-example-abbreviated.md)

   • 3 SMART primary objectives with measurable targets
   • Launch criteria: 100 test transactions, <3s processing, PCI compliance
   • 5 functional requirements (FR1-FR5) with full acceptance criteria
   • 4 non-functional requirements: Performance, Security, Reliability, Usability
   • Constraints, assumptions, and explicit out-of-scope items

4. Workflow Test Log (workflow-test-log.md)

   • Complete happy path: status → brief → research → PRD → validate → decompose → generate-spec
   • 10 edge cases tested: missing files, duplicates, invalid input, error handling
   • Validation quality tests: vague language, unmeasurable criteria, missing sections
   • All tests passed with proper error handling

Key Patterns Demonstrated:

Problem Statement Format:

What problem + Who experiences + Frequency + Business impact

Example: "Our e-commerce platform lacks payment processing, forcing
customers through manual invoices. This affects 100% of transactions
(1,000/month), causing 45% cart abandonment and $2.4M lost revenue annually."

Success Metric Format:

Metric name: Baseline → Target within Timeframe

Example: "Checkout conversion rate: 55% → 75% within 30 days post-launch"

Functional Requirement Structure:

• Description: What the system must do
• User Story: As a [user], I want [capability], so that [benefit]
• Inputs: What triggers this functionality
• Outputs: What results or changes occur
• Business Rules: Constraints or special conditions
• Acceptance Criteria: Specific, testable conditions (Given/When/Then)
• Priority: Must Have / Should Have / Could Have
• Dependencies: Other requirements or systems

Example Functional Requirement:

### FR1: Credit/Debit Card Payment Processing

**Description**: Process credit and debit card payments securely in real-time

**User Story**: As an online shopper, I want to pay with my credit/debit card
directly on the checkout page, so that I can complete my purchase immediately

**Inputs**: Card number, expiration, CVV, billing address, purchase amount

**Outputs**: Payment confirmation, transaction ID, order receipt via email

**Business Rules**:
- Accept Visa, Mastercard, Amex, Discover
- Require CVV for all transactions
- Maximum transaction: $10,000

**Acceptance Criteria**:
- [ ] Given valid card, when submitted, then processes in <3 seconds
- [ ] Given invalid card, when submitted, then clear error message displays
- [ ] Given successful payment, when completes, then email sent within 30 seconds

**Priority**: Must Have

**Dependencies**: Stripe API integration, email service

Running the Example Workflow:

# Set up test environment
mkdir -p /tmp/test-prd && cd /tmp/test-prd
mkdir -p docs/prds

# Step 1: Check status (no projects yet)
bash /path/to/prd-authoring.sh status

# Step 2: Create product brief
bash /path/to/prd-authoring.sh brief "Payment Gateway Integration"
# Edit docs/prds/payment-gateway-integration/product-brief.md

# Step 3: Verify brief completeness
bash /path/to/prd-authoring.sh status payment-gateway-integration

# Step 4: Create research document
bash /path/to/prd-authoring.sh research payment-gateway-integration
# Edit docs/prds/payment-gateway-integration/research.md

# Step 5: Create PRD
bash /path/to/prd-authoring.sh create-prd payment-gateway-integration
# Edit docs/prds/payment-gateway-integration/prd.md

# Step 6: Validate PRD (lenient mode for drafts)
bash /path/to/prd-authoring.sh validate-prd payment-gateway-integration --lenient

# Step 7: Validate PRD (strict mode when complete)
bash /path/to/prd-authoring.sh validate-prd payment-gateway-integration

# Step 8: Decompose into epics
bash /path/to/prd-authoring.sh decompose payment-gateway-integration
# Edit docs/prds/payment-gateway-integration/epics.md

# Step 9: Generate spec proposal for first epic
bash /path/to/prd-authoring.sh generate-spec payment-gateway-integration "Payment Processing Core"
# Edit files in docs/changes/payment-processing-core/

Expected Timeline for Example Project:

• Product brief: 2-4 hours (stakeholder interviews + writing)
• Research: 4-8 hours (competitive analysis + market research)
• PRD creation: 8-16 hours (requirements definition + validation)
• Epic decomposition: 4-8 hours (breaking into deliverable units)
• Total: 18-36 hours of upfront planning before any code is written

ROI of Planning:

• Upfront time: ~1 week of planning work
• Prevents: Weeks of rework from misalignment or unclear requirements
• Enables: Parallel development, clear sprint planning, stakeholder buy-in
• Result: Faster delivery with less rework and higher quality outcomes

For complete examples with full content, see the examples/ directory.

---

Troubleshooting

Common Errors and Solutions

Error: "docs/prds/ directory does not exist"

Symptom: Any command fails with this error

Cause: Project not initialized with SynthesisFlow structure

Solution:

# Create directory structure manually
mkdir -p docs/prds

# OR use project-init skill to create full SynthesisFlow structure
# (if available)

Prevention: Always run from project root, ensure docs/ directory exists

---

Error: "Product brief already exists"

Symptom: brief command fails when trying to create new brief

Cause: Project directory and brief file already exist

Solution:

# Option 1: Use different project name
bash scripts/prd-authoring.sh brief "Payment Gateway V2"

# Option 2: Edit existing brief
vim docs/prds/payment-gateway-integration/product-brief.md

# Option 3: Delete and recreate (CAUTION: loses work)
rm -rf docs/prds/payment-gateway-integration
bash scripts/prd-authoring.sh brief "Payment Gateway Integration"

Prevention: Run status command first to check what exists

---

Error: "Project directory does not exist. Run 'brief' command first"

Symptom: research, create-prd, or other commands fail

Cause: Trying to run commands before creating product brief

Solution:

# Follow proper workflow order
bash scripts/prd-authoring.sh brief "Project Name"  # Step 1
bash scripts/prd-authoring.sh research project-name # Step 2
bash scripts/prd-authoring.sh create-prd project-name # Step 3

Prevention: Always run status command to see what step you're on

---

Warning: "Research document not found. PRD quality may be reduced"

Symptom: When running create-prd, prompted to continue without research

Cause: Skipping research step before creating PRD

Solution:

# Recommended: Cancel and create research first
# Press 'n' when prompted

# Create research
bash scripts/prd-authoring.sh research project-name
# Edit research.md

# Then create PRD
bash scripts/prd-authoring.sh create-prd project-name

When to skip: Very small projects or internal tools where competitive landscape doesn't matter

Risk: PRD may lack data-driven insights, miss competitive features, or make invalid assumptions

---

Validation Error: "Vague language detected"

Symptom: validate-prd reports vague terms like "should", "might", "probably", "good", "fast"

Cause: Requirements or success criteria are not specific enough

Solution: Replace vague language with specific, measurable terms:

Vague	Specific
"fast performance"	"response time <200ms at 95th percentile"
"good user experience"	"task completion rate >85% without help"
"should support many users"	"must support 10,000 concurrent users"
"might improve conversion"	"target 25% increase in conversion rate"
"better security"	"zero critical vulnerabilities in security audit"

Example Fix:

# Before (vague)
The system should provide fast payment processing with good security.

# After (specific)
The system must process payments in under 3 seconds at 95th percentile
with PCI DSS Level 1 compliance and zero critical security vulnerabilities.

---

Validation Error: "Success criteria may lack measurable targets"

Symptom: validate-prd warns that success criteria are not measurable

Cause: Success criteria use qualitative language without numeric targets

Solution: Add specific numbers, percentages, or metrics to each success criterion:

# Before (unmeasurable)
- Improve customer satisfaction
- Reduce checkout time
- Increase conversion rates

# After (measurable)
- Customer satisfaction: NPS score 35 → 55 within 3 months
- Checkout time: Reduce from 180 seconds to 45 seconds (90th percentile)
- Conversion rate: Increase from 55% to 75% within 30 days post-launch

Format: [Metric name]: [Baseline] → [Target] within [Timeframe]

---

Validation Error: "Some functional requirements may lack acceptance criteria"

Symptom: Validation reports missing acceptance criteria for requirements

Cause: Requirements defined without testable acceptance criteria

Solution: Add specific, testable acceptance criteria in Given/When/Then format:

### FR1: Payment Processing

**Acceptance Criteria**:
- [ ] Given valid card details, when customer submits payment,
      then transaction processes in <3 seconds
- [ ] Given invalid card number, when customer submits,
      then error message displays and payment is not processed
- [ ] Given successful payment, when transaction completes,
      then confirmation email sent within 30 seconds
- [ ] Given network timeout, when Stripe API fails,
      then system retries 3 times before showing error

Rule of thumb: 3-5 acceptance criteria per functional requirement

---

Error: "Epics document already exists"

Symptom: decompose command fails

Cause: Epic decomposition already created for this project

Solution:

# Option 1: Edit existing epics document
vim docs/prds/project-name/epics.md

# Option 2: Delete and regenerate (CAUTION: loses work)
rm docs/prds/project-name/epics.md
bash scripts/prd-authoring.sh decompose project-name

# Option 3: Create new version
bash scripts/prd-authoring.sh decompose project-name-v2

---

Error: "Spec proposal directory already exists"

Symptom: generate-spec command fails

Cause: Spec proposal already generated for this epic

Solution:

# Option 1: Edit existing spec proposal
vim docs/changes/epic-name/proposal.md

# Option 2: Use different epic name
bash scripts/prd-authoring.sh generate-spec project-name "Epic Name V2"

# Option 3: Delete and regenerate (CAUTION: loses work)
rm -rf docs/changes/epic-name
bash scripts/prd-authoring.sh generate-spec project-name "Epic Name"

---

Quality Issues

Issue: PRD validation passes but requirements are still unclear

Symptom: Validation says "GOOD" but team still doesn't understand what to build

Cause: Validation catches patterns but can't ensure complete clarity

Solution:

1. Review each requirement with stakeholders
2. Ask: "How would we test this?" and "What does 'done' look like?"
3. Add concrete examples to requirements
4. Create mock-ups or wireframes for UI requirements
5. Write example API requests/responses for backend requirements

Prevention: Use peer review - have another team member read the PRD

---

Issue: Epic dependencies are complex and create bottlenecks

Symptom: Many epics depend on each other, limiting parallel work

Cause: PRD scope may be too ambitious or epics not properly sized

Solution:

1. Consider phasing: MVP with fewer dependencies first, enhancements later
2. Refactor epic boundaries to reduce coupling
3. Document dependencies explicitly and plan sprint sequence accordingly
4. Accept some coupling is normal (just make it visible)

Example refactoring:

# Before (high coupling)
Epic 1: Full payment system
Epic 2: Full CRM integration
Epic 3: Full accounting integration

# After (reduced coupling)
Epic 1: Basic payment processing (foundation, no dependencies)
Epic 2: Payment methods & saved cards (depends on Epic 1)
Epic 3: CRM integration (depends on Epic 1, can parallelize with Epic 2)
Epic 4: Accounting integration (depends on Epic 1, can parallelize with Epic 2-3)

---

Issue: Stakeholders disagree on objectives during PRD review

Symptom: PRD review meeting reveals conflicting goals among stakeholders

Cause: PRD authoring surfaced alignment issues early (this is actually good!)

Solution:

1. Document all perspectives in PRD
2. Escalate to decision-maker for prioritization
3. Update PRD to reflect final decision with rationale
4. Add assumptions section documenting deferred concerns

This is a feature, not a bug: Better to discover misalignment during planning than during development

Example documentation:

## Decision Log

**Decision**: Prioritize B2C checkout experience over B2B invoice workflow

**Rationale**: 80% of revenue from B2C, B2B customers can continue with
manual invoices short-term. B2C automation has higher ROI ($1.8M vs $400K).

**Stakeholder Positions**:
- Sales Team: Wanted B2B priority (their main workflow)
- Product: Recommended B2C (higher revenue impact)
- Final Decision (CEO): B2C for MVP, B2B in Phase 2

**Assumptions**: B2B customers tolerate manual invoices for 6 more months

---

Issue: Research is taking too long and delaying project start

Symptom: Week 3 of research and still gathering data

Cause: Analysis paralysis, trying to achieve perfect information

Solution:

1. Time-box research: 4-8 hours maximum
2. Focus on questions that impact requirements (not interesting tangents)
3. Use 80/20 rule: Get 80% of insights from 20% of research
4. Document confidence levels and assumptions
5. Perfect information is impossible - make best decision with available data

Time-boxing template:

## Research Time Budget (8 hours total)

- Competitive analysis (3 hours): Review 3-5 competitors
- Market research (2 hours): Size, trends, growth rate
- User feedback (2 hours): Review existing support tickets, user interviews
- Technical research (1 hour): Industry standards, compliance requirements

## Out of Scope for This Research:
- Deep dive into every competitor feature
- Primary user research (use existing data)
- Building prototypes
- Financial modeling beyond high-level ROI

---

Issue: PRD keeps changing during validation iterations

Symptom: After 5+ rounds of validation, still making changes

Cause: Unclear initial vision or excessive perfectionism

Solution:

1. Accept that PRDs iterate - 2-3 validation cycles is normal
2. After 3 cycles, lock the PRD and proceed
3. Future changes can be versioned (create prd-v2.md if needed)
4. Use lenient mode for draft validation, strict mode for final pass

Locking criteria:

• All required sections present
• Zero critical validation errors
• Stakeholders have reviewed and approved
• Team understands what to build

Version control:

# Lock v1
mv docs/prds/project/prd.md docs/prds/project/prd-v1.md

# Create v2 for major changes
bash scripts/prd-authoring.sh create-prd project-v2

# OR: Make incremental updates with changelog
# Add "## Changelog" section to PRD documenting changes

---

Integration Issues

Issue: Unclear how to transition from PRD to spec-authoring

Symptom: PRD complete but don't know what to do next

Solution: Follow the epic → spec transition workflow:

# 1. Ensure PRD decomposed into epics
bash scripts/prd-authoring.sh decompose project-name

# 2. Review and populate epics.md with requirements breakdown

# 3. Generate spec proposal for first epic
bash scripts/prd-authoring.sh generate-spec project-name "Epic 1 Name"

# 4. Populate the spec proposal files:
#    - proposal.md: Epic scope and objectives
#    - spec-delta.md: Technical requirements and design
#    - tasks.md: Implementation breakdown

# 5. Transition to spec-authoring workflow
#    Use spec-authoring skill to create Spec PR from proposal

Traceability chain:

Business Goal
  → PRD Objective
    → Epic
      → Spec Proposal
        → Spec PR
          → GitHub Issues
            → Code Implementation

---

Issue: Multiple people working on same PRD causing conflicts

Symptom: Git merge conflicts in PRD files

Solution:

1. Designate one PRD author (typically Product Manager or Tech Lead)
2. Use comments/suggestions for collaboration instead of direct edits
3. Hold review meetings to discuss changes instead of simultaneous editing
4. Use git branches for major structural changes

Workflow:

# Author makes changes
git checkout -b prd-update-objectives
# Edit PRD
git commit -m "Update objectives based on stakeholder feedback"
git push

# Reviewers comment on GitHub PR
# Author incorporates feedback
# Merge when approved

---

Notes

• PRDs are strategic documents: They define WHAT and WHY, not HOW
• Specs provide implementation details: Use spec-authoring for HOW
• PRDs can span multiple specs: One PRD may generate 3-10 specs via epics
• Research informs better decisions: Don't skip it (even if brief)
• Validation is a guide, not gospel: Use judgment on what to enforce
• Epic decomposition bridges strategy and execution: Critical handoff point
• Iteration is expected: Few PRDs are perfect on first draft
• Traceability is essential: Link specs → epics → PRD → business objectives
• This workflow is front-loaded: Invest time early to save rework later
• Stakeholder alignment is the goal: Documents are the medium, not the end