| name | prd-authoring |
| description | 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. |
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:
- Initial idea or concept identified
- Product brief created (problem, solution, users, value)
- Market research conducted (competitors, landscape, opportunities)
- PRD created (objectives, requirements, constraints, assumptions)
- PRD validated against quality standards
- Epic decomposition prepares transition to development
- 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
bash scripts/prd-authoring.sh brief "Analytics Dashboard"
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
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
: Best developer experience, comprehensive features
: Card payments, Apple Pay, Google Pay
: Add BNPL options (Klarna, Affirm)
: 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"
bash scripts/prd-authoring.sh status project-name
Usage Example
Scenario: Researching real-time notification system
bash scripts/prd-authoring.sh research notification-system
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"
bash scripts/prd-authoring.sh status project-name
Usage Example
Scenario: Creating PRD for mobile app authentication
bash scripts/prd-authoring.sh status mobile-auth
bash scripts/prd-authoring.sh create-prd mobile-auth
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:
Quality Checks:
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:
- Locate the line number in the PRD
- Understand the specific problem
- Revise the content to address the issue
- 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
bash scripts/prd-authoring.sh validate-prd api-redesign
bash scripts/prd-authoring.sh validate-prd api-redesign
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%
:
Epic 1 (Payment Processing Core) must be complete
: 2 sprints
:
Cryptocurrency payments
BNPL options (Phase 2)
---
: Enable refund processing and accounting integration
:
Implement full and partial refund flows
Integrate with accounting system (Salesforce)
Real-time transaction sync
Automated reconciliation reporting
Refund notification emails
:
FR3: Refund Processing (100%)
Objective 3: Automate payment reconciliation
:
Refunds process within 5-7 business days
100% transaction sync accuracy
80% reduction in manual reconciliation time
:
Epic 1 (Payment Processing Core) must be complete
: 2 sprints
:
Chargeback handling (manual process)
Dispute management (Phase 2)
---
: Achieve PCI DSS compliance and implement fraud prevention
:
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
:
NFR2: Security (100%)
NFR3: Reliability (transaction logging)
:
PCI DSS compliance certification
Zero security incidents post-launch
Fraud detection blocks 95%+ of suspicious transactions
:
Epic 1 (Payment Processing Core) - security built on top
: 2 sprints
:
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:
- Epic 1 (Sprint 1-3)
- Epic 4 in parallel with Epic 1 sprints 2-3 (Sprint 2-4)
- 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
bash scripts/prd-authoring.sh validate-prd user-management
bash scripts/prd-authoring.sh decompose user-management
bash scripts/prd-authoring.sh generate-specs user-management
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:
-
Generate spec proposals from epics (optional):
bash scripts/prd-authoring.sh generate-specs project-name
-
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
-
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:
- Use sprint-planner to select approved specs for sprint
- Epic structure from PRD informs sprint scope
- PRD success criteria guide sprint goals
Integration with doc-indexer
PRD documents are indexed alongside specs:
bash scripts/doc-indexer.sh
Integration with project-init
When initializing new projects:
- Project-init may suggest running prd-authoring for new projects
- Creates
docs/prds/ directory structure
- Recommends starting with
status command
Common Workflows
Greenfield Project (Idea to PRD)
Complete workflow for brand new project:
bash scripts/prd-authoring.sh status
bash scripts/prd-authoring.sh brief "New Project"
bash scripts/prd-authoring.sh research new-project
bash scripts/prd-authoring.sh create-prd new-project
bash scripts/prd-authoring.sh validate-prd new-project
bash scripts/prd-authoring.sh decompose new-project
bash scripts/prd-authoring.sh generate-specs new-project
Brownfield Enhancement (Existing System)
Workflow for adding features to existing system:
bash scripts/prd-authoring.sh brief "System Enhancement"
bash scripts/prd-authoring.sh research system-enhancement
bash scripts/prd-authoring.sh create-prd system-enhancement
bash scripts/prd-authoring.sh validate-prd system-enhancement
bash scripts/prd-authoring.sh decompose system-enhancement
Skipping Steps (When Prerequisites Exist)
If some work already exists:
bash scripts/prd-authoring.sh status project-name
bash scripts/prd-authoring.sh create-prd project-name
bash scripts/prd-authoring.sh validate-prd project-name
bash scripts/prd-authoring.sh decompose project-name
Error Handling and Troubleshooting
General Issues
docs/prds/ directory doesn't exist:
mkdir -p docs/prds
Permission denied when running scripts:
chmod +x scripts/prd-authoring.sh
Script not found:
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:
-
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
-
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
-
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
-
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:
mkdir -p /tmp/test-prd && cd /tmp/test-prd
mkdir -p docs/prds
bash /path/to/prd-authoring.sh status
bash /path/to/prd-authoring.sh brief "Payment Gateway Integration"
bash /path/to/prd-authoring.sh status payment-gateway-integration
bash /path/to/prd-authoring.sh research payment-gateway-integration
bash /path/to/prd-authoring.sh create-prd payment-gateway-integration
bash /path/to/prd-authoring.sh validate-prd payment-gateway-integration --lenient
bash /path/to/prd-authoring.sh validate-prd payment-gateway-integration
bash /path/to/prd-authoring.sh decompose payment-gateway-integration
bash /path/to/prd-authoring.sh generate-spec payment-gateway-integration "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:
mkdir -p docs/prds
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:
bash scripts/prd-authoring.sh brief "Payment Gateway V2"
vim docs/prds/payment-gateway-integration/product-brief.md
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:
bash scripts/prd-authoring.sh brief "Project Name"
bash scripts/prd-authoring.sh research project-name
bash scripts/prd-authoring.sh create-prd project-name
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:
bash scripts/prd-authoring.sh research project-name
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:
vim docs/prds/project-name/epics.md
rm docs/prds/project-name/epics.md
bash scripts/prd-authoring.sh decompose project-name
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:
vim docs/changes/epic-name/proposal.md
bash scripts/prd-authoring.sh generate-spec project-name "Epic Name V2"
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:
- Review each requirement with stakeholders
- Ask: "How would we test this?" and "What does 'done' look like?"
- Add concrete examples to requirements
- Create mock-ups or wireframes for UI requirements
- 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:
- Consider phasing: MVP with fewer dependencies first, enhancements later
- Refactor epic boundaries to reduce coupling
- Document dependencies explicitly and plan sprint sequence accordingly
- 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:
- Document all perspectives in PRD
- Escalate to decision-maker for prioritization
- Update PRD to reflect final decision with rationale
- 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:
- Time-box research: 4-8 hours maximum
- Focus on questions that impact requirements (not interesting tangents)
- Use 80/20 rule: Get 80% of insights from 20% of research
- Document confidence levels and assumptions
- 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:
- Accept that PRDs iterate - 2-3 validation cycles is normal
- After 3 cycles, lock the PRD and proceed
- Future changes can be versioned (create prd-v2.md if needed)
- 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:
mv docs/prds/project/prd.md docs/prds/project/prd-v1.md
bash scripts/prd-authoring.sh create-prd project-v2
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:
bash scripts/prd-authoring.sh decompose project-name
bash scripts/prd-authoring.sh generate-spec project-name "Epic 1 Name"
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:
- Designate one PRD author (typically Product Manager or Tech Lead)
- Use comments/suggestions for collaboration instead of direct edits
- Hold review meetings to discuss changes instead of simultaneous editing
- Use git branches for major structural changes
Workflow:
git checkout -b prd-update-objectives
git commit -m "Update objectives based on stakeholder feedback"
git push
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
