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:

List existing upstream artifacts:

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

Reference only existing documents in traceability tags

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

NEVER use placeholders like BRD-XXX or TBD

Do NOT create missing upstream artifacts - skip functionality instead

Before creating a PRD, read:

Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md 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. Template: ai_dev_flow/PRD/PRD-TEMPLATE.md Creation Rules: ai_dev_flow/PRD/PRD_CREATION_RULES.md 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):

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

ML/AI agent? -> Agent-Based n8n workflow/automation? -> Automation-Focused 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):

Product positioning statements Key messaging themes Feature descriptions for marketing User-facing documentation requirements Help text and tooltips Error messages (user-visible) Success confirmations Onboarding content 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.32.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!

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 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 Numbering Convention: Start with 2 digits and expand only as needed. - ✅ Correct: PRD-01, PRD-99, PRD-102 - ❌ Incorrect: PRD-001, PRD-009 (extra leading zero not required)

ID Matching: PRD ID does NOT need to match BRD ID (PRD-09 may implement BRD-16).

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-00_TRACEABILITY_MATRIX.md

Step 11: Update Upstream BRD Traceability (MANDATORY)

CRITICAL - Often Missed: When creating a PRD, you MUST update the parent BRD's traceability section.

Process: 1. Open the upstream BRD (e.g., docs/BRD/BRD-01_platform.md) 2. Locate the ## Traceability section 3. Add this PRD to Downstream Artifacts: ```markdown - Downstream Artifacts: PRD-01

Commit BRD update with PRD creation (single commit)

Why This Matters:

Enables bidirectional navigation between BRD and PRD Impact analysis: BRD changes show affected PRDs Audit compliance: Regulators require bidirectional traceability

Reference: See .claude/skills/doc-flow/SHARED_CONTENT.md Section 4.3 "Bidirectional Traceability Update Workflow" for complete guidance.

Step 12: Validate PRD

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 Upstream BRD traceability section updated with this PRD 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 Missing dual scores: Both SYS-Ready and EARS-Ready scores required Incorrect section structure: Must be exactly 21 sections (1-21) in order Missing Section 10 content: Customer-Facing Content is MANDATORY User Stories scope violation: Section 8 must stay at PRD-level (no EARS/BDD detail) ADR forward references: Don't write "See ADR-033" (ADRs don't exist yet) Missing @brd tags: Layer 2 must include Layer 1 tags ID format errors: Use unified format PRD.NN.TT.SS (not F-XXX, US-XXX, etc.) Missing EARS Enhancement Appendix: Section 20 required for EARS-Ready score Missing upstream BRD update: Must add PRD reference to parent BRD's Downstream Artifacts 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