majiayu000 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
briefcommand first - Brief exists, no research: Run
researchcommand - Brief and research exist: Run
create-prdcommand - PRD exists but incomplete: Edit PRD or run
validate-prdfor specific issues - PRD complete and validated: Run
decomposecommand 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.mdwith YAML frontmatter and template sections
Step 3: Populate Product Brief
Work with the user to fill in the template sections:
---
title: Payment Gateway Integration
type: product-brief
status: draft
created: 2025-11-04
updated: 2025-11-04
---
# Product Brief: Payment Gateway Integration
## Problem Statement
Our e-commerce platform currently lacks payment processing capabilities,
forcing customers to complete purchases via manual invoice. This creates
friction in the buying process and reduces conversion rates.
## Target Users
- Online shoppers making purchases on our platform
- Merchants managing sales and refunds
- Finance team reconciling payments
## Proposed Solution
Integrate a third-party payment gateway (Stripe) to enable secure,
real-time payment processing with support for multiple payment methods.
## Value Proposition
- Customers: Seamless checkout experience with instant confirmation
- Business: Increased conversion rates, automated payment reconciliation
- Merchants: Simplified refund and chargeback management
## Success Metrics
- 80% reduction in checkout abandonment rate
- 95% of payments processed within 3 seconds
- Zero PCI compliance violations
- Support for 5+ payment methods by launch
Step 4: Review and Refine
Review the brief with stakeholders:
- Ensure problem statement is clear and specific
- Validate target users are well-defined
- Confirm value proposition is compelling
- Verify success metrics are measurable
Step 5: Save and Commit
Once the brief is complete:
git add docs/prds/payment-gateway/product-brief.md
git commit -m "docs: Add product brief for payment gateway"
Step 6: Check Status
Run status command to confirm brief is complete:
bash scripts/prd-authoring.sh status payment-gateway
Usage Example
Scenario: Starting a new analytics dashboard project
# Create product brief
bash scripts/prd-authoring.sh brief "Analytics Dashboard"
# Edit docs/prds/analytics-dashboard/product-brief.md
# Fill in problem, users, solution, value, metrics
# Verify completion
bash scripts/prd-authoring.sh status analytics-dashboard
Error Handling
Project directory already exists:
- Check if brief already created:
ls docs/prds/project-name/ - Either use different name or edit existing brief
- Use status command to see what exists
Vague problem statement:
- Ask probing questions to get specifics
- What exactly is broken or missing?
- Who is affected and how often?
- What's the business impact?
Unmeasurable success metrics:
- Convert vague goals to specific numbers
- "Better performance" → "95th percentile response time < 200ms"
- "Improved UX" → "Task completion rate > 85%"
The research Command
Purpose
Guide users through market research and competitive analysis to inform PRD requirements with data-driven insights.
Workflow
Step 1: Verify Brief Exists
Check that product brief is complete:
bash scripts/prd-authoring.sh status project-name
If brief is missing or incomplete, complete it first before conducting research.
Step 2: Run Research Creation Script
Execute the script to create research document structure:
bash scripts/prd-authoring.sh research project-name
This creates docs/prds/project-name/research.md with template sections.
Step 3: Define Research Questions
Work with the user to identify key questions:
- Who are the main competitors in this space?
- What features do they offer?
- What are their strengths and weaknesses?
- What market opportunities exist?
- What do users say about existing solutions?
- What technical approaches do competitors use?
Step 4: Conduct Research
Guide the user through research activities:
Competitive Analysis:
- Identify 3-5 direct competitors
- Document their key features and pricing
- Note what they do well and poorly
- Identify gaps in their offerings
Market Analysis:
- Research market size and trends
- Identify target market segments
- Document regulatory or compliance requirements
- Note industry standards and best practices
User Research (if applicable):
- Review user feedback on competitor products
- Conduct user interviews or surveys
- Analyze support tickets or feature requests
- Document pain points and unmet needs
Step 5: Populate Research Document
Document findings in structured format:
---
title: Payment Gateway Research
type: research
status: complete
created: 2025-11-04
updated: 2025-11-04
---
# Research: Payment Gateway Integration
## Competitive Analysis
### Competitor 1: Stripe
- **Strengths**: Developer-friendly API, excellent documentation, 135+ currencies
- **Weaknesses**: Higher fees for international cards (3.9% + $0.30)
- **Key Features**: Recurring billing, fraud detection, mobile SDKs
- **Market Position**: Leader in developer-focused payment processing
### Competitor 2: PayPal
- **Strengths**: Brand recognition, buyer protection, wide adoption
- **Weaknesses**: Higher dispute rates, complex API
- **Key Features**: PayPal checkout, Venmo integration, buyer credit
- **Market Position**: Consumer-focused, trusted brand
### Competitor 3: Square
- **Strengths**: Unified POS and online payments, simple pricing
- **Weaknesses**: Limited international support, fewer currencies
- **Key Features**: In-person + online, inventory management, analytics
- **Market Position**: Small business focus, retail-oriented
## Market Insights
- Payment processing market growing 12% annually
- Mobile payments expected to reach 60% of e-commerce by 2026
- PCI DSS 4.0 compliance required by March 2025
- Buy-now-pay-later (BNPL) options increasing in demand
## User Feedback Analysis
Common pain points with existing solutions:
- Complex integration requiring weeks of development
- Hidden fees and confusing pricing structures
- Poor error messages during failed transactions
- Lack of real-time reconciliation with accounting systems
Desired features:
- One-click checkout experience
- Multiple payment method support (cards, wallets, BNPL)
- Instant refund processing
- Detailed transaction analytics
## Technical Considerations
- REST API vs SDK integration trade-offs
- Webhook reliability for async event handling
- PCI compliance scope (SAQ-A vs SAQ-A-EP)
- Tokenization for recurring payments
- 3D Secure 2.0 for fraud prevention
## Recommendations
1. **Choose Stripe**: Best developer experience, comprehensive features
2. **Priority features**: Card payments, Apple Pay, Google Pay
3. **Phase 2**: Add BNPL options (Klarna, Affirm)
4. **Compliance**: Implement SAQ-A eligible integration (no card data storage)
Step 6: Extract Key Insights
Summarize findings that will inform PRD:
- Which features are table stakes vs differentiators?
- What technical approaches are proven?
- What user needs are unmet by competitors?
- What constraints exist (compliance, budget, timeline)?
Step 7: Review and Commit
git add docs/prds/project-name/research.md
git commit -m "docs: Add market research for project-name"
# Verify research is complete
bash scripts/prd-authoring.sh status project-name
Usage Example
Scenario: Researching real-time notification system
# Create research document
bash scripts/prd-authoring.sh research notification-system
# Conduct analysis
# - Compare Firebase, Pusher, Ably, custom WebSocket
# - Review scalability and cost at different volumes
# - Document latency requirements from user research
# Document findings in docs/prds/notification-system/research.md
# Verify completion
bash scripts/prd-authoring.sh status notification-system
Error Handling
Brief doesn't exist yet:
- Complete product brief first
- Research should be informed by brief's problem statement
Research is too broad:
- Focus on questions that impact requirements
- Avoid analysis paralysis - perfect is the enemy of done
- Time-box research activities (e.g., 4 hours max)
No clear competitors:
- Research adjacent solutions or alternative approaches
- Document why no direct competitors exist
- Analyze components that could be assembled
Conflicting data sources:
- Document multiple perspectives
- Note confidence levels in findings
- Prioritize primary research over secondary
The create-prd Command
Purpose
Generate a comprehensive Product Requirements Document from product brief and research findings. The PRD is the authoritative definition of what will be built and how success will be measured.
Workflow
Step 1: Verify Prerequisites
Check that brief and research are complete:
bash scripts/prd-authoring.sh status project-name
Both documents should exist and be marked complete before creating PRD.
Step 2: Run PRD Creation Script
Execute the script to create PRD structure:
bash scripts/prd-authoring.sh create-prd project-name
This creates docs/prds/project-name/prd.md with comprehensive template sections.
Step 3: Define Objectives
Work with the user to articulate clear project objectives:
Good objectives are:
- Specific: Clearly state what will be achieved
- Measurable: Include quantifiable targets
- Achievable: Realistic given constraints
- Relevant: Aligned with business goals
- Time-bound: Have clear deadlines
Example:
## Objectives
### Primary Objectives
1. **Enable online payment processing**
- Support credit/debit card payments with PCI compliance
- Process payments in under 3 seconds (95th percentile)
- Launch by Q2 2026
2. **Increase conversion rates**
- Reduce checkout abandonment from 45% to 15%
- Support 5+ payment methods by launch
- Enable one-click checkout for returning customers
3. **Automate payment reconciliation**
- Eliminate manual invoice processing
- Real-time sync with accounting system
- Reduce finance team reconciliation time by 80%
### Secondary Objectives
1. Enable subscription and recurring billing (Phase 2)
2. Support international currencies (Phase 2)
3. Provide merchant analytics dashboard (Phase 3)
Step 4: Define Success Criteria
Specify measurable criteria that indicate project success:
## Success Criteria
### Launch Criteria (Must-Have)
- [ ] Successfully process 100 test transactions with 0% failure rate
- [ ] PCI DSS compliance validation passed (SAQ-A)
- [ ] Checkout flow completion time < 60 seconds (90th percentile)
- [ ] Support Visa, Mastercard, American Express, Apple Pay, Google Pay
- [ ] 99.9% payment processing uptime over 30-day period
### Success Metrics (3 Months Post-Launch)
- [ ] 10,000+ successful transactions processed
- [ ] Checkout abandonment rate < 20% (vs 45% baseline)
- [ ] Average payment processing time < 2.5 seconds
- [ ] Customer satisfaction score > 4.5/5 for checkout experience
- [ ] Zero security incidents or PCI compliance violations
- [ ] 90% reduction in manual payment reconciliation time
### Stretch Goals
- [ ] Checkout abandonment < 15%
- [ ] Support 10+ payment methods
- [ ] Process 50,000+ transactions per month
Step 5: Document Functional Requirements
List specific, testable functional requirements:
## Functional Requirements
### FR1: Payment Processing
- **Description**: Process credit/debit card payments securely
- **Inputs**: Card details, payment amount, customer info
- **Outputs**: Transaction confirmation, receipt
- **Acceptance Criteria**:
- Accepts Visa, Mastercard, American Express, Discover
- Validates card details before submission
- Returns clear error messages for failed transactions
- Generates unique transaction ID for each payment
- Sends confirmation email within 30 seconds
### FR2: Payment Method Management
- **Description**: Support multiple payment methods
- **Inputs**: Customer payment method preferences
- **Outputs**: Saved payment methods, default selection
- **Acceptance Criteria**:
- Customers can save multiple payment methods
- Supports cards, Apple Pay, Google Pay
- Allows setting default payment method
- Enables payment method deletion
- Tokenizes card data (no raw card storage)
### FR3: Refund Processing
- **Description**: Enable full and partial refunds
- **Inputs**: Original transaction ID, refund amount
- **Outputs**: Refund confirmation, updated transaction status
- **Acceptance Criteria**:
- Merchants can issue refunds within 90 days
- Supports partial refunds
- Refunds process within 5-7 business days
- Customer receives refund notification
- Accounting system updated automatically
Step 6: Document Non-Functional Requirements
Specify quality attributes and constraints:
## Non-Functional Requirements
### NFR1: Performance
- Payment processing response time < 3 seconds (95th percentile)
- Checkout page load time < 2 seconds
- Support 1000 concurrent transactions
- 99.9% uptime SLA
### NFR2: Security
- PCI DSS Level 1 compliance
- TLS 1.3 for all payment data transmission
- Tokenization of card data (no storage of card numbers)
- 3D Secure 2.0 for fraud prevention
- Regular security audits and penetration testing
### NFR3: Reliability
- Automatic retry for transient failures
- Graceful degradation if payment gateway is down
- Transaction logging for audit trail
- Daily backups of transaction data
### NFR4: Usability
- Checkout flow completable in < 5 steps
- Mobile-responsive design
- WCAG 2.1 AA accessibility compliance
- Support for 10+ languages
### NFR5: Scalability
- Handle 10x traffic during peak shopping periods
- Horizontal scaling for increased load
- Database optimization for transaction queries
Step 7: Document Constraints and Assumptions
Be explicit about limitations and dependencies:
## Constraints
- Must use Stripe as payment provider (existing contract)
- Cannot store raw credit card numbers (PCI compliance)
- Must integrate with existing Salesforce CRM
- Launch deadline: June 30, 2026 (non-negotiable)
- Budget: $150k for development and first year operational costs
## Assumptions
- Average transaction value: $75
- Expected transaction volume: 5,000/month initially
- Users have modern browsers (last 2 versions)
- Finance team will handle chargebacks manually
- Stripe API will maintain backward compatibility
- Customer support will handle payment-related inquiries
Step 8: Define Out of Scope
Clearly state what will NOT be included:
## Out of Scope (For This Phase)
- Cryptocurrency payments
- Subscription/recurring billing (deferred to Phase 2)
- International currencies beyond USD (Phase 2)
- In-person/POS payment processing
- Custom payment gateway integration
- Buy-now-pay-later (BNPL) options (Phase 2)
- Merchant analytics dashboard (Phase 3)
Step 9: Review and Refine
Review the complete PRD with stakeholders:
- Are objectives clear and measurable?
- Are requirements specific and testable?
- Are success criteria appropriate?
- Are constraints and assumptions documented?
- Is scope well-defined?
Step 10: Save and Commit
git add docs/prds/project-name/prd.md
git commit -m "docs: Add PRD for project-name"
# Check status
bash scripts/prd-authoring.sh status project-name
Usage Example
Scenario: Creating PRD for mobile app authentication
# Verify prerequisites
bash scripts/prd-authoring.sh status mobile-auth
# Create PRD structure
bash scripts/prd-authoring.sh create-prd mobile-auth
# Populate PRD with:
# - Objectives: Enable secure mobile login
# - Success Criteria: 99.9% auth success rate, <2s login time
# - Functional Requirements: Biometric auth, 2FA, password reset
# - Non-Functional Requirements: Security (OAuth 2.0), Performance
# - Constraints: Must support iOS 15+ and Android 10+
# Commit completed PRD
git add docs/prds/mobile-auth/prd.md
git commit -m "docs: Add PRD for mobile authentication"
Error Handling
Brief or research missing:
- Complete prerequisites first
- Use status command to identify what's missing
- PRD quality depends on foundation work
Requirements are too vague:
- Make requirements specific and measurable
- Add clear acceptance criteria for each requirement
- Ask: "How would we test this?"
Scope is too large:
- Break into phases (MVP, Phase 2, Phase 3)
- Define clear out-of-scope items
- Focus on core value proposition first
Success criteria not measurable:
- Convert qualitative goals to quantitative metrics
- "Better UX" → "Task completion rate > 85%"
- "Fast performance" → "P95 response time < 200ms"
Conflicting requirements:
- Document the conflict explicitly
- Escalate to stakeholders for prioritization
- Note decision rationale in PRD
The validate-prd Command
Purpose
Validate PRD quality against standards and best practices. Catches common issues like missing sections, vague requirements, and unmeasurable success criteria.
Workflow
Step 1: Run Validation Script
Execute the validation check:
bash scripts/prd-authoring.sh validate-prd project-name
Step 2: Review Validation Report
The script checks for:
Completeness:
- YAML frontmatter present with required fields
- Objectives section exists and non-empty
- Success criteria section exists with measurable items
- Functional requirements section exists
- Non-functional requirements section exists
- Constraints section exists
- Assumptions section exists
Quality Checks:
- Requirements are specific (not vague language like "should", "might", "probably")
- Success criteria are measurable (include numbers/percentages)
- Acceptance criteria defined for each requirement
- No ambiguous terms ("fast", "good", "better" without quantification)
- Out of scope section clarifies boundaries
SMART Criteria (for objectives and requirements):
- Specific: Clearly defined, not vague
- Measurable: Quantifiable success metrics
- Achievable: Realistic given constraints
- Relevant: Aligned with business goals
- Time-bound: Has clear deadlines
Output example:
=== PRD Validation Report ===
Project: payment-gateway
File: docs/prds/payment-gateway/prd.md
Completeness: 8/8 ✓
- ✓ YAML frontmatter present
- ✓ Objectives section (3 objectives defined)
- ✓ Success criteria section (12 criteria, 10 measurable)
- ✓ Functional requirements (8 requirements)
- ✓ Non-functional requirements (5 requirements)
- ✓ Constraints (5 constraints documented)
- ✓ Assumptions (6 assumptions documented)
- ✓ Out of scope (7 items excluded)
Quality Issues: 3
⚠ Line 45: Success criterion lacks measurement - "improve user experience"
Suggestion: Specify measurable UX metric (e.g., "task completion rate > 85%")
⚠ Line 67: Vague language in FR3 - "reasonable time"
Suggestion: Define specific time threshold (e.g., "within 5 seconds")
⚠ Line 89: Ambiguous requirement - "should support most payment methods"
Suggestion: List specific payment methods required
Recommendations:
1. Quantify vague success criteria
2. Replace ambiguous terms with specific values
3. Add acceptance criteria to FR5 and FR6
Overall: GOOD (Minor revisions recommended)
Step 3: Address Issues
For each issue identified:
- 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
# 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-prdcommand first - Check project name spelling
- Use
statuscommand to confirm PRD location
Too many validation errors:
- Use lenient mode during drafting
- Focus on completing content first, polish later
- Address critical issues before minor ones
False positives:
- Some domain-specific terms may be flagged incorrectly
- Document rationale in PRD if intentionally using flagged term
- Validation is a guide, not absolute law
Requirements conflict with constraints:
- Validation may flag logical conflicts
- Review with stakeholders to resolve
- Update either requirements or constraints
The decompose Command
Purpose
Break down a validated PRD into epics for sprint planning. Epics are independently deliverable units of work that align with PRD objectives and can be further broken down into user stories during sprint planning.
Workflow
Step 1: Validate PRD First
Ensure PRD passes validation:
bash scripts/prd-authoring.sh validate-prd project-name
Only decompose validated PRDs to ensure quality input.
Step 2: Run Decomposition Script
Execute the epic decomposition:
bash scripts/prd-authoring.sh decompose project-name
This creates docs/prds/project-name/epics.md with epic breakdown.
Step 3: Identify Epic Boundaries
Work with the user to group requirements into logical epics:
Epic Definition Criteria:
- Independently deliverable (provides value on its own)
- Aligns with one or more PRD objectives
- Can be completed in 2-4 sprints
- Has clear scope boundaries
- Minimal dependencies on other epics (where possible)
Common Epic Patterns:
- By user flow (e.g., "User Registration Epic", "Checkout Epic")
- By technical layer (e.g., "API Development Epic", "UI Epic")
- By component (e.g., "Payment Processing Epic", "Notification Epic")
- By phase (e.g., "MVP Epic", "Phase 2 Features Epic")
Step 4: Define Each Epic
For each epic, document:
---
title: Payment Gateway Epics
type: epic-breakdown
prd: docs/prds/payment-gateway/prd.md
status: draft
created: 2025-11-04
updated: 2025-11-04
---
# Epic Breakdown: Payment Gateway
## Epic 1: Payment Processing Core
**Objective**: Enable basic credit/debit card payment processing
**Scope**:
- Integrate Stripe SDK
- Implement payment form with card input
- Process payment transactions
- Handle success/failure responses
- Generate transaction receipts
**Requirements Coverage**:
- FR1: Payment Processing (100%)
- NFR1: Performance (payment processing time)
- NFR2: Security (TLS, tokenization)
**Success Criteria**:
- Process 100 test transactions with 0% failure
- P95 processing time < 3 seconds
- PCI SAQ-A compliance validated
**Dependencies**:
- None (foundational epic)
**Estimated Effort**: 3 sprints
**Out of Scope**:
- Refund processing (Epic 3)
- Multiple payment methods (Epic 2)
- Subscription billing (Phase 2)
---
## Epic 2: Payment Methods
**Objective**: Support multiple payment methods (Apple Pay, Google Pay)
**Scope**:
- Integrate Apple Pay SDK
- Integrate Google Pay SDK
- Add payment method selection UI
- Save payment methods for returning customers
- Set default payment method
**Requirements Coverage**:
- FR2: Payment Method Management (100%)
- NFR4: Usability (checkout flow simplicity)
**Success Criteria**:
- Support 5+ payment methods by launch
- One-click checkout for returning customers
- Payment method save rate > 60%
**Dependencies**:
- Epic 1 (Payment Processing Core) must be complete
**Estimated Effort**: 2 sprints
**Out of Scope**:
- Cryptocurrency payments
- BNPL options (Phase 2)
---
## Epic 3: Refunds and Reconciliation
**Objective**: Enable refund processing and accounting integration
**Scope**:
- Implement full and partial refund flows
- Integrate with accounting system (Salesforce)
- Real-time transaction sync
- Automated reconciliation reporting
- Refund notification emails
**Requirements Coverage**:
- FR3: Refund Processing (100%)
- Objective 3: Automate payment reconciliation
**Success Criteria**:
- Refunds process within 5-7 business days
- 100% transaction sync accuracy
- 80% reduction in manual reconciliation time
**Dependencies**:
- Epic 1 (Payment Processing Core) must be complete
**Estimated Effort**: 2 sprints
**Out of Scope**:
- Chargeback handling (manual process)
- Dispute management (Phase 2)
---
## Epic 4: Security and Compliance
**Objective**: Achieve PCI DSS compliance and implement fraud prevention
**Scope**:
- Implement 3D Secure 2.0
- Complete PCI DSS self-assessment (SAQ-A)
- Set up transaction logging and audit trails
- Implement fraud detection rules
- Security audit and penetration testing
**Requirements Coverage**:
- NFR2: Security (100%)
- NFR3: Reliability (transaction logging)
**Success Criteria**:
- PCI DSS compliance certification
- Zero security incidents post-launch
- Fraud detection blocks 95%+ of suspicious transactions
**Dependencies**:
- Epic 1 (Payment Processing Core) - security built on top
**Estimated Effort**: 2 sprints
**Out of Scope**:
- Advanced fraud ML models (Phase 2)
- Biometric authentication (future)
Step 5: Map Epic Dependencies
Create dependency graph:
## Epic Dependencies
Epic 1: Payment Processing Core (Foundational) │ ├─→ Epic 2: Payment Methods (Depends on Epic 1) ├─→ Epic 3: Refunds and Reconciliation (Depends on Epic 1) └─→ Epic 4: Security and Compliance (Depends on Epic 1)
Recommended Sequence:
- 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
# 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-prdfirst - 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-nameFor 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
- Run
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:
# 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:
- Project-init may suggest running prd-authoring for new projects
- Creates
docs/prds/directory structure - Recommends starting with
statuscommand
Common Workflows
Greenfield Project (Idea to PRD)
Complete workflow for brand new project:
# 1. Assess starting point
bash scripts/prd-authoring.sh status
# 2. Create product brief
bash scripts/prd-authoring.sh brief "New Project"
# Edit docs/prds/new-project/product-brief.md
# 3. Conduct research
bash scripts/prd-authoring.sh research new-project
# Edit docs/prds/new-project/research.md
# 4. Create PRD
bash scripts/prd-authoring.sh create-prd new-project
# Edit docs/prds/new-project/prd.md
# 5. Validate PRD
bash scripts/prd-authoring.sh validate-prd new-project
# Fix any issues and re-validate
# 6. Decompose into epics
bash scripts/prd-authoring.sh decompose new-project
# Review docs/prds/new-project/epics.md
# 7. Generate spec proposals
bash scripts/prd-authoring.sh generate-specs new-project
# 8. Transition to spec-authoring for each epic
Brownfield Enhancement (Existing System)
Workflow for adding features to existing system:
# 1. Start with research (brief may be lightweight)
bash scripts/prd-authoring.sh brief "System Enhancement"
# Brief can reference existing system docs
bash scripts/prd-authoring.sh research system-enhancement
# Research focuses on gap analysis
# 2. Create focused PRD for enhancement
bash scripts/prd-authoring.sh create-prd system-enhancement
# PRD defines delta from current state
# 3. Validate and decompose
bash scripts/prd-authoring.sh validate-prd system-enhancement
bash scripts/prd-authoring.sh decompose system-enhancement
# 4. Proceed to spec-authoring
Skipping Steps (When Prerequisites Exist)
If some work already exists:
# Check what exists
bash scripts/prd-authoring.sh status project-name
# If research exists but no PRD, skip to create-prd
bash scripts/prd-authoring.sh create-prd project-name
# If PRD exists but needs validation
bash scripts/prd-authoring.sh validate-prd project-name
# If PRD validated, go straight to decompose
bash scripts/prd-authoring.sh decompose project-name
Error Handling and Troubleshooting
General Issues
docs/prds/ directory doesn't exist:
# Solution: Create directory structure
mkdir -p docs/prds
# Or run project-init if full structure needed
Permission denied when running scripts:
# Solution: Make script executable
chmod +x scripts/prd-authoring.sh
Script not found:
# Solution: Run from project root or use absolute path
cd /path/to/project
bash scripts/prd-authoring.sh status
Comma
…(truncated)