doc-prd

Purpose

Create Product Requirements Documents (PRD) - Layer 2 artifact in the SDD workflow that defines product features, user needs, measurable success criteria, and KPIs.

Layer: 2

Upstream: BRD (Layer 1)

Downstream Artifacts: EARS (Layer 3), BDD (Layer 4), ADR (Layer 5)

Prerequisites

Upstream Artifact Verification (CRITICAL)

Before creating this document, you MUST:

1. List existing upstream artifacts:

   ls docs/BRD/ docs/PRD/ 2>/dev/null
   

2. Reference only existing documents in traceability tags

3. Use null only when upstream artifact type genuinely doesn't exist

4. NEVER use placeholders like BRD-XXX or TBD

5. Do NOT create missing upstream artifacts - skip functionality instead

Before creating a PRD, read:

1. Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md
2. Upstream BRD: Read the BRD that drives this PRD Note on Sectioned BRDs: If BRD is split into multiple section files (0-18), read ALL files as ONE logical document. See PRD_CREATION_RULES.md Section 22.
3. Template: ai_dev_flow/PRD/PRD-TEMPLATE.md
4. Creation Rules: ai_dev_flow/PRD/PRD_CREATION_RULES.md
5. Validation Rules: ai_dev_flow/PRD/PRD_VALIDATION_RULES.md

When to Use This Skill

Use doc-prd when:

• Have completed BRD (Layer 1)
• Need to define product features and user requirements
• Translating business needs to product specifications
• Establishing KPIs and success metrics
• You are at Layer 2 of the SDD workflow

PRD-Specific Guidance

1. Required Sections (21 Total)

PRD documents require exactly 21 numbered sections (1-21). See ai_dev_flow/PRD/PRD-TEMPLATE.md for complete structure.

Section 1. Document Control (MANDATORY - First section):

• Status, Version, Date Created, Last Updated
• Author, Reviewer, Approver
• BRD Reference (@brd: BRD.NN.EE.SS)
• SYS-Ready Score: >=90% required (format: XX% (Target: >=90%))
• EARS-Ready Score: >=90% required (format: XX% (Target: >=90%))
• Template Variant (Standard/Agent-Based/Automation-Focused)
• Document Revision History table

All 21 Sections (in order):

1. Document Control: Metadata, versioning, dual scoring (SYS-Ready + EARS-Ready >=90%)
2. Executive Summary: Business value and timeline overview (2-3 sentences)
3. Problem Statement: Current state, business impact, opportunity assessment
4. Target Audience & User Personas: Primary users, secondary users, business stakeholders
5. Success Metrics (KPIs): Primary KPIs, secondary KPIs, success criteria by phase
6. Goals & Objectives: Primary business goals, secondary objectives, stretch goals
7. Scope & Requirements: In scope features, out of scope items, dependencies, assumptions
8. User Stories & User Roles: Role definitions, story summaries (PRD-level only, no EARS/BDD detail)
9. Functional Requirements: User journey mapping, capability requirements
10. Customer-Facing Content & Messaging (MANDATORY): Product positioning, messaging, user-facing content
11. Acceptance Criteria: Business acceptance, technical acceptance, quality assurance
12. Constraints & Assumptions: Business/technical/external constraints, key assumptions
13. Risk Assessment: High-risk items, risk mitigation plan
14. Success Definition: Go-live criteria, post-launch validation, measurement timeline
15. Stakeholders & Communication: Core team, stakeholders, communication plan
16. Implementation Approach: Development phases, testing strategy
17. Budget & Resources: Development/operational budget, resource requirements
18. Traceability: Upstream sources, downstream artifacts, traceability tags, validation evidence
19. References: Internal documentation, external standards, domain references, technology references
20. EARS Enhancement Appendix: EARS pattern templates and requirement syntax guidance
21. Quality Assurance & Testing Strategy: QA standards, testing strategy

Critical Notes:

• All 21 sections are MANDATORY with explicit numbering (## N. Title format)
• Section 10 (Customer-Facing Content) is blocking - must contain substantive content
• Section 8 (User Stories) must include layer separation scope note
• Section 21 (QA & Testing Strategy) moved from BRD as technical QA belongs at product level

2. Dual Scoring Requirements

PRD documents require two quality scores in Document Control:

Score	Purpose	Threshold
SYS-Ready Score	Readiness for SYS creation	>=90%
EARS-Ready Score	Readiness for EARS creation	>=90%

Format: XX% (Target: >=90%)

SYS-Ready Scoring Criteria (100%):

• Product Requirements Completeness (40%): All 21 sections, measurable KPIs, acceptance criteria, stakeholder analysis
• Technical Readiness (30%): System boundaries, quality attributes quantified, Architecture Decision Requirements
• Business Alignment (20%): ROI validated, market analysis, success metrics, risk mitigation
• Traceability (10%): Upstream BRD references, downstream links

EARS-Ready Scoring Criteria (100%):

• Business Requirements Clarity (40%): SMART objectives, functional requirements, acceptance criteria
• Requirements Maturity (35%): System boundaries, stakeholder requirements, problem statement
• EARS Translation Readiness (20%): User journeys, quality attributes quantified
• Strategic Alignment (5%): Domain-specific business logic references

3. Template Variant Selection

Variant	Sections	Use Case
Standard	1-21 (21)	Business features, core platform (DEFAULT)
Agent-Based	1-15 (15)	ML/AI agents, intelligent systems
Automation-Focused	1-12 (12)	n8n workflows, event processing

Selection Criteria:

1. ML/AI agent? -> Agent-Based
2. n8n workflow/automation? -> Automation-Focused
3. Otherwise -> Standard (default)

4. User Stories Scope (Section 8)

Layer Separation Principle:

• PRD (Layer 2): User role definitions, story summaries, product-level acceptance criteria
• EARS (Layer 3): Detailed behavioral scenarios (WHEN-THE-SHALL-WITHIN format)
• BDD (Layer 4): Executable test scenarios (Given-When-Then format)

MANDATORY Scope Note (include in Section 8):

This section provides role definitions and story summaries. Detailed behavioral requirements are captured in EARS; executable test specifications are in BDD feature files.

User Story Format: "As a [role], I want [capability] so that [benefit]"

PRD-Level Content (INCLUDE):

• User role definitions (personas)
• Story titles and summaries (2-3 sentences max)
• Product-level acceptance criteria
• Business value justification

NOT PRD-Level (EXCLUDE):

• EARS-level specifications -> Layer 3
• BDD-level test scenarios -> Layer 4
• Technical implementation details -> Layer 6/7
• System architecture decisions -> ADR (Layer 5)

5. Customer-Facing Content (Section 10) - MANDATORY

Status: BLOCKING - error if missing or placeholder-only

Required Content Categories (minimum 3):

1. Product positioning statements
2. Key messaging themes
3. Feature descriptions for marketing
4. User-facing documentation requirements
5. Help text and tooltips
6. Error messages (user-visible)
7. Success confirmations
8. Onboarding content
9. Release notes template

6. Architecture Decision Requirements (Section 18)

Purpose: Elaborate BRD Section 7.2 topics with technical content (options, criteria).

Layer Separation:

BRD Section 7.2          ->    PRD Section 18         ->    ADR
(WHAT & WHY)                   (HOW to evaluate)           (Final decision)
-------------------------------------------------------------------
Business drivers               Technical options           Selected option
Business constraints           Evaluation criteria         Trade-off analysis

PRD Section 18 Format:

##### BRD.NN.21.SS: [Topic Name]

**Upstream**: BRD-NN section 7.2.X

**Technical Options**:
1. **[Option A]**: [Description]
2. **[Option B]**: [Description]

**Evaluation Criteria**:
- **[Criterion 1]**: [Measurable target]
- **[Criterion 2]**: [Measurable target]

**Product Constraints**:
- [Constraint 1]

**Decision Timeline**: [Milestone reference]

**ADR Requirements**: [What ADR must decide]

CRITICAL: Do NOT reference specific ADR numbers (ADR-01, ADR-033, etc.) - ADRs don't exist yet!

7. EARS Enhancement Appendix (Section 20)

Purpose: Provides structured requirements for EARS transformation.

Required Subsections:

20.1 Timing Profile Matrix:

Operation	p50	p95	p99	Unit	Trigger Event	Notes
[operation]	[value]	[value]	[value]	ms	[event]	[constraints]

20.2 Boundary Value Matrix:

Threshold	Operator	Value	At Boundary	Above	Below
[name]	>= or > or <= or <	[value]	[behavior]	[behavior]	[behavior]

20.3 State Transition Diagram: Mermaid stateDiagram-v2 with error states

20.4 Fallback Path Documentation:

Dependency	Failure Mode	Detection	Fallback Behavior	Timeout	Recovery

20.5 EARS-Ready Checklist: All timing, boundary, state, fallback items verified

Tag Format Convention

Notation	Format	Artifacts	Purpose
Dash	TYPE-NN	ADR, SPEC, CTR, IPLAN, ICON	Technical artifacts - file references
Dot	TYPE.NN.TT.SS	BRD, PRD, EARS, BDD, SYS, REQ, IMPL, TASKS	Hierarchical - element references

Key Distinction:

• @adr: ADR-033 -> Points to document ADR-033_slug.md
• @brd: BRD.17.01.01 -> Points to element 01.01 inside BRD-017.md

Unified Element ID Format (MANDATORY)

Pattern: PRD.{DOC_NUM}.{ELEM_TYPE}.{SEQ} (4 segments, dot-separated)

Element Type	Code	Example
Functional Requirement	01	PRD.02.01.01
Quality Attribute	02	PRD.02.02.01
Constraint	03	PRD.02.03.01
Assumption	04	PRD.02.04.01
Dependency	05	PRD.02.05.01
Acceptance Criteria	06	PRD.02.06.01
Risk	07	PRD.02.07.01
Metric	08	PRD.02.08.01
User Story	09	PRD.02.09.01
Use Case	11	PRD.02.11.01
Feature Item	22	PRD.02.22.01
Stakeholder Need	24	PRD.02.24.01

REMOVED Patterns (Do NOT use):

• AC-XXX -> Use PRD.NN.06.SS
• FR-XXX -> Use PRD.NN.01.SS
• F-XXX -> Use PRD.NN.09.SS
• US-XXX -> Use PRD.NN.09.SS

Cumulative Tagging Requirements

Layer 2 (PRD): Must include tags from Layer 1 (BRD)

Tag Count: 1 tag (@brd)

Format:

## 18. Traceability

### Traceability Tags

**Required Tags** (Cumulative Tagging Hierarchy - Layer 2):
```markdown
@brd: BRD.01.01.03, BRD.01.01.10

• BRD.01.01.03 - Business requirements driving this product
• BRD.01.01.10 - Success criteria from business case

Upstream Sources:

• BRD-01 - Parent business requirements

Downstream Artifacts:

• EARS-NN (to be created) - Formal requirements
• BDD-NN (to be created) - Test scenarios

## Creation Process

### Step 1: Read Parent BRD

Read and understand the BRD that drives this PRD.

**Sectioned BRD Handling**:
If BRD is split into multiple section files (folder structure `docs/BRD/BRD-NN_{slug}/`):
1. Read ALL section files (BRD-NN.0 through BRD-NN.18)
2. Treat as ONE logical document
3. Extract information holistically (no section-to-section mapping)

### Step 2: Reserve ID Number

Check `docs/PRD/` for next available ID number (e.g., PRD-01, PRD-02).

**ID Matching**: PRD ID does NOT need to match BRD ID (PRD-009 may implement BRD-016).

### Step 3: Create PRD Folder and Files

**Folder structure** (DEFAULT - nested folder per document):
1. Create folder: `docs/PRD/PRD-NN_{slug}/`
2. Create index file: `docs/PRD/PRD-NN_{slug}/PRD-NN.0_index.md`
3. Create section files: `docs/PRD/PRD-NN_{slug}/PRD-NN.S_{section_type}.md`

**Example**:

docs/PRD/PRD-01_user_authentication/ PRD-01.0_index.md PRD-01.1_executive_summary.md PRD-01.2_problem_statement.md ...

**OPTIONAL** (for small documents <25KB): `docs/PRD/PRD-NN_{slug}.md` (monolithic)

### Step 4: Complete Document Control

Fill all required metadata fields:
- Status, Version, Dates, Author/Reviewer/Approver
- BRD Reference with `@brd` tag
- SYS-Ready Score and EARS-Ready Score (both >=90%)
- Template Variant
- Document Revision History table

### Step 5: Complete Core Sections (2-17)

**Section 2-3**: Problem context and business impact
**Section 4-6**: Users, KPIs, goals
**Section 7-9**: Scope, user stories, functional requirements
**Section 10**: Customer-facing content (MANDATORY)
**Section 11-14**: Acceptance criteria, constraints, risks, success
**Section 15-17**: Stakeholders, implementation, budget

### Step 6: Complete Traceability (Section 18)

- Add upstream BRD references
- Document downstream artifact placeholders
- Include Architecture Decision Requirements elaboration
- Add bidirectional reference table if cross-PRD dependencies exist

### Step 7: Complete References (Section 19)

Internal documentation, external standards, domain and technology references.

### Step 8: Complete EARS Enhancement Appendix (Section 20)

- Timing Profile Matrix (p50/p95/p99)
- Boundary Value Matrix (explicit operators)
- State Transition Diagram (with error states)
- Fallback Path Documentation
- EARS-Ready Checklist

### Step 9: Complete QA Strategy (Section 21)

Quality standards and testing strategy (moved from BRD).

### Step 10: Create/Update Traceability Matrix

**MANDATORY**: Create or update `docs/PRD/PRD-000_TRACEABILITY_MATRIX.md`

### Step 11: Validate PRD

```bash
# PRD validation
python ai_dev_flow/scripts/validate_prd.py docs/PRD/PRD-NN_{slug}/

# Link integrity
python ai_dev_flow/scripts/validate_links.py --path docs/PRD/

# Cumulative tagging validation
python ai_dev_flow/scripts/validate_tags_against_docs.py --artifact PRD-NN --expected-layers brd --strict

Validation Checklist

Structure (21 Sections):

• All 21 numbered sections present (1-21)
• Document Control (Section 1) at top with all required fields
• Customer-Facing Content (Section 10) has substantive content
• User Stories (Section 8) includes layer separation scope note
• EARS Enhancement Appendix (Section 20) completed
• Quality Assurance & Testing Strategy (Section 21) completed

Document Control Required Fields:

• Status, Version, Date Created, Last Updated
• Author, Reviewer, Approver
• BRD Reference with @brd tag
• SYS-Ready Score >=90%
• EARS-Ready Score >=90%
• Template Variant specified
• Document Revision History table initialized

Content Quality:

• Parent BRD identified and referenced
• Problem-Goals framework completed
• User personas and user stories defined (PRD-level only)
• Product features specified with priority levels
• KPIs quantified (measurable metrics with targets)
• Quality attributes quantified (performance, reliability)
• Risk assessment with mitigation strategies
• Architecture Decision Requirements listed (NO ADR numbers)
• EARS Enhancement Appendix complete (timing, boundary, state, fallback)

Traceability:

• Cumulative tags: @brd included
• Traceability matrix created/updated
• No ADR forward references
• No broken links

Size Limits:

• File size <50,000 tokens (standard) or <100,000 tokens (maximum)

Post-Creation Validation (MANDATORY - NO CONFIRMATION)

CRITICAL: Execute this validation loop IMMEDIATELY after document creation.

LOOP:
  1. Run: python ai_dev_flow/scripts/validate_cross_document.py --document {doc_path} --auto-fix
  2. IF errors fixed: GOTO LOOP (re-validate)
  3. IF warnings fixed: GOTO LOOP (re-validate)
  4. IF unfixable issues: Log for manual review, continue
  5. IF clean: Mark VALIDATED, proceed

Validation Command

# Per-document validation (Phase 1)
python ai_dev_flow/scripts/validate_cross_document.py --document docs/PRD/PRD-NN_slug.md --auto-fix

# Layer validation (Phase 2) - run when all PRD documents complete
python ai_dev_flow/scripts/validate_cross_document.py --layer PRD --auto-fix

Validation Codes Reference

Code	Description	Severity
XDOC-001	Referenced requirement ID not found	ERROR
XDOC-002	Missing cumulative tag (@brd)	ERROR
XDOC-003	Upstream document not found	ERROR
XDOC-006	Tag format invalid	ERROR
XDOC-009	Missing traceability section	ERROR
FWDREF-E001	Forward reference to non-existent ADR	ERROR

Quality Gate

Blocking: YES - Cannot proceed to EARS/SYS creation until validation passes with 0 errors.

Common Pitfalls

1. Missing dual scores: Both SYS-Ready and EARS-Ready scores required
2. Incorrect section structure: Must be exactly 21 sections (1-21) in order
3. Missing Section 10 content: Customer-Facing Content is MANDATORY
4. User Stories scope violation: Section 8 must stay at PRD-level (no EARS/BDD detail)
5. ADR forward references: Don't write "See ADR-033" (ADRs don't exist yet)
6. Missing @brd tags: Layer 2 must include Layer 1 tags
7. ID format errors: Use unified format PRD.NN.TT.SS (not F-XXX, US-XXX, etc.)
8. Missing EARS Enhancement Appendix: Section 20 required for EARS-Ready score

Template Binding (MANDATORY)

When creating PRD documents, use EXACTLY these metadata values:

tags:
  - prd                 # REQUIRED - Use 'prd' NOT 'product-prd', 'feature-prd'
  - layer-2-artifact    # REQUIRED - Layer identifier

custom_fields:
  document_type: prd    # REQUIRED - Use 'prd' NOT 'product-requirements'
  artifact_type: PRD    # REQUIRED - Uppercase
  layer: 2              # REQUIRED - PRD is Layer 2
  architecture_approaches: [ai-agent-based]  # REQUIRED - Array format

FORBIDDEN Values:

• Tags: product-prd, feature-prd, product-requirements
• document_type: product-requirements, product_requirements
• architecture_approach: value (singular form)

Diagram Standards

All diagrams MUST use Mermaid syntax. Text-based diagrams (ASCII art, box drawings) are prohibited. See: ai_dev_flow/DIAGRAM_STANDARDS.md and mermaid-gen skill.

---

Next Skill

After creating PRD, use:

doc-ears - Create formal EARS requirements (Layer 3)

The EARS will:

• Reference this PRD as upstream source
• Include @brd and @prd tags (cumulative)
• Use WHEN-THE-SHALL-WITHIN format
• Formalize PRD features into requirements

Related Resources

• Main Guide: ai_dev_flow/SPEC_DRIVEN_DEVELOPMENT_GUIDE.md
• PRD Schema: ai_dev_flow/PRD/PRD_SCHEMA.yaml
• PRD Template: ai_dev_flow/PRD/PRD-TEMPLATE.md
• PRD Creation Rules: ai_dev_flow/PRD/PRD_CREATION_RULES.md
• PRD Validation Rules: ai_dev_flow/PRD/PRD_VALIDATION_RULES.md
• PRD README: ai_dev_flow/PRD/README.md
• Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md

Section Templates (DEFAULT for all PRD documents):

• Structure: docs/PRD/PRD-NN_{slug}/PRD-NN.S_{slug}.md
• Index template: ai_dev_flow/PRD/PRD-SECTION-0-TEMPLATE.md
• Content template: ai_dev_flow/PRD/PRD-SECTION-TEMPLATE.md
• Reference: ai_dev_flow/ID_NAMING_STANDARDS.md

Quick Reference

PRD Purpose: Define product features and user needs

Layer: 2

Tags Required: @brd (1 tag)

Key Sections:

• Section 1: Document Control with dual scoring (SYS-Ready + EARS-Ready >=90%)
• Section 8: User Stories (PRD-level only)
• Section 10: Customer-Facing Content (MANDATORY)
• Section 18: Traceability with Architecture Decision Requirements
• Section 20: EARS Enhancement Appendix

Next: doc-ears