# Prd Authoring

> Use this skill for early-stage project planning through Product Requirements Documents (PRDs). Guides users from initial project ideas through product briefs, market research, PRD creation, validation, and epic decomposition. Triggers include "create PRD", "product brief", "validate requirements", or beginning project inception activities.

- Skill: `majiayu000/prd-authoring` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/prd-authoring`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/prd-authoring/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/prd-authoring

---


# 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
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
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:

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

```bash
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
bash scripts/prd-authoring.sh status payment-gateway
```

#### Usage Example

**Scenario**: Starting a new analytics dashboard project

```bash
# 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
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
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:

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

```bash
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

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

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

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

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

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

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

```bash
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

```bash
# 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
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
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:

```bash
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
bash scripts/prd-authoring.sh validate-prd project-name --lenient
```

#### Usage Example

**Scenario**: Validating API redesign PRD

```bash
# 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
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
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:

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

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

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

```bash
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
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

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

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
# 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**:
```bash
# Solution: Create directory structure
mkdir -p docs/prds
# Or run project-init if full structure needed
```

**Permission denied when running scripts**:
```bash
# Solution: Make script executable
chmod +x scripts/prd-authoring.sh
```

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

### Comma

…(truncated)