bmad-method 6.0.0-alpha.1 → 6.0.0-alpha.10

package/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/instructions.md

@@ -2,45 +2,66 @@
 
 <workflow name="create-ux-design">
 
-<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
+<critical>The workflow execution engine is governed by: {project-root}/{bmad_folder}/core/tasks/workflow.xml</critical>
 <critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
 <critical>This workflow uses ADAPTIVE FACILITATION - adjust your communication style based on {user_skill_level}</critical>
 <critical>The goal is COLLABORATIVE UX DESIGN through visual exploration, not content generation</critical>
 <critical>Communicate all responses in {communication_language} and tailor to {user_skill_level}</critical>
 <critical>Generate all documents in {document_output_language}</critical>
 <critical>SAVE PROGRESS after each major step - use <template-output> tags throughout</critical>
-
 <critical>DOCUMENT OUTPUT: Professional, specific, actionable UX design decisions WITH RATIONALE. User skill level ({user_skill_level}) affects conversation style ONLY, not document content.</critical>
+<critical>Input documents specified in workflow.yaml input_file_patterns - workflow engine handles fuzzy matching, whole vs sharded document discovery automatically</critical>
+<critical>⚠️ ABSOLUTELY NO TIME ESTIMATES - NEVER mention hours, days, weeks, months, or ANY time-based predictions. AI has fundamentally changed development speed - what once took teams weeks/months can now be done by one person in hours. DO NOT give ANY time estimates whatsoever.</critical>
+<critical>⚠️ CHECKPOINT PROTOCOL: After EVERY <template-output> tag, you MUST follow workflow.xml substep 2c: SAVE content to file immediately → SHOW checkpoint separator (━━━━━━━━━━━━━━━━━━━━━━━) → DISPLAY generated content → PRESENT options [a]Advanced Elicitation/[c]Continue/[p]Party-Mode/[y]YOLO → WAIT for user response. Never batch saves or skip checkpoints.</critical>
 
-<step n="0" goal="Validate workflow and extract project configuration">
+<step n="0" goal="Validate workflow readiness" tag="workflow-status">
+<action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
 
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
-  <param>mode: data</param>
-  <param>data_request: project_config</param>
-</invoke-workflow>
+<check if="status file not found">
+  <output>No workflow status file found. Create UX Design can run standalone or as part of BMM planning workflow.</output>
+  <output>For standalone use, we'll gather requirements as we go. For integrated use, run `workflow-init` first for better context.</output>
+  <action>Set standalone_mode = true</action>
+</check>
 
-<check if="status_exists == false">
-  <output>**Note: No Workflow Status File Found**
+<check if="status file found">
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+  <action>Parse workflow_status section</action>
+  <action>Check status of "create-design" workflow</action>
+  <action>Get project_level from YAML metadata</action>
+  <action>Find first non-completed workflow (next expected workflow)</action>
+
+  <check if="create-design status is file path (already completed)">
+    <output>⚠️ UX Design already completed: {{create-design status}}</output>
+    <ask>Re-running will overwrite the existing UX design. Continue? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. Use workflow-status to see your next step.</output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
 
-Create UX Design can run standalone or as part of the BMM planning workflow.
+  <check if="create-design is not the next expected workflow">
+    <output>⚠️ Next expected workflow: {{next_workflow}}. UX Design is out of sequence.</output>
+    <ask>Continue with UX Design anyway? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. Run {{next_workflow}} instead.</output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
 
-For standalone use, we'll gather requirements as we go.
-For integrated use, run `workflow-init` first for better context.
-</output>
-<action>Set mode: standalone</action>
+<action>Set standalone_mode = false</action>
+<action>Store {{project_level}} for scoping decisions</action>
 </check>
+</step>
 
-<check if="status_exists == true">
-  <action>Store {{status_file_path}} for later updates</action>
-  <action>Store {{project_level}} for scoping decisions</action>
-  <action>Set mode: integrated</action>
-</check>
+<step n="0.5" goal="Discover and load input documents">
+<invoke-protocol name="discover_inputs" />
+<note>After discovery, these content variables are available: {prd_content}, {product_brief_content}, {epics_content}, {brainstorming_content}, {document_project_content}</note>
 </step>
 
 <step n="1a" goal="Confirm project understanding or gather basic context">
   <critical>A UX designer must understand the WHY before designing the HOW</critical>
 
-<action>Attempt to load context documents using fuzzy matching: - PRD: {prd_file} - Product Brief: {brief_file} - Brainstorming: {brainstorm_file}
+<action>Review loaded context from Step 0.5: {prd_content}, {product_brief_content}, {epics_content}, {brainstorming_content}
 </action>
 
   <check if="documents_found">
@@ -1116,12 +1137,16 @@ Based on your deployment intent: {{recommendation}}
 
 <action>Save final document to {default_output_file}</action>
 
-  <check if="tracking_mode == true">
-    <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
-      <param>mode: update</param>
-      <param>action: complete_workflow</param>
-      <param>workflow_name: create-ux-design</param>
-    </invoke-workflow>
+  <check if="standalone_mode != true">
+    <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+    <action>Find workflow_status key "create-design"</action>
+    <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
+    <action>Update workflow_status["create-design"] = "{default_output_file}"</action>
+    <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+
+    <action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
+    <action>Determine next agent from path file based on next workflow</action>
+
   </check>
 
 <ask>🎨 **One more thing!** Want to see your design come to life?

package/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/workflow.yaml

@@ -4,7 +4,7 @@ description: "Collaborative UX design facilitation workflow that creates excepti
 author: "BMad"
 
 # Critical variables from config
-config_source: "{project-root}/bmad/bmm/config.yaml"
+config_source: "{project-root}/{bmad_folder}/bmm/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
@@ -12,31 +12,82 @@ document_output_language: "{config_source}:document_output_language"
 user_skill_level: "{config_source}:user_skill_level"
 date: system-generated
 
-# Input requirements - We work from PRD, Brief, or Brainstorming docs
-recommended_inputs:
-  - prd: "Product Requirements Document with features and user journeys"
-  - product_brief: "Product brief with vision and target users"
-  - brainstorming: "Brainstorming documents with ideas and concepts"
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+# Strategy: How to load sharded documents (FULL_LOAD, SELECTIVE_LOAD, INDEX_GUIDED)
+input_file_patterns:
+  prd:
+    description: "Features and user journeys (optional)"
+    whole: "{output_folder}/*prd*.md"
+    sharded: "{output_folder}/*prd*/index.md"
+    load_strategy: "FULL_LOAD"
 
-# Input file references (fuzzy matched from output folder)
-prd_file: "{output_folder}/bmm-PRD.md or PRD.md or product-requirements.md"
-brief_file: "{output_folder}/product-brief.md or brief.md or project-brief.md"
-brainstorm_file: "{output_folder}/brainstorming.md or brainstorm.md or ideation.md"
+  product_brief:
+    description: "Product vision and target users (optional)"
+    whole: "{output_folder}/*brief*.md"
+    sharded: "{output_folder}/*brief*/index.md"
+    load_strategy: "FULL_LOAD"
+
+  epics:
+    description: "Epic and story breakdown (optional)"
+    whole: "{output_folder}/*epic*.md"
+    sharded: "{output_folder}/*epic*/index.md"
+    load_strategy: "FULL_LOAD"
+
+  brainstorming:
+    description: "Brainstorming ideas and concepts (optional)"
+    whole: "{output_folder}/*brainstorm*.md"
+    sharded: "{output_folder}/*brainstorm*/index.md"
+    load_strategy: "FULL_LOAD"
+
+  document_project:
+    description: "Brownfield project documentation (optional)"
+    sharded: "{output_folder}/index.md"
+    load_strategy: "INDEX_GUIDED"
 
 # Module path and component files
-installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/create-ux-design"
+installed_path: "{project-root}/{bmad_folder}/bmm/workflows/2-plan-workflows/create-ux-design"
 instructions: "{installed_path}/instructions.md"
 validation: "{installed_path}/checklist.md"
 template: "{installed_path}/ux-design-template.md"
 
-# Knowledge bases for intelligent UX decisions
-ux_pattern_catalog: "{installed_path}/ux-pattern-catalog.yaml"
-color_psychology: "{installed_path}/color-psychology.yaml"
-layout_patterns: "{installed_path}/layout-patterns.yaml"
-
 # Output configuration - Progressive saves throughout workflow
 default_output_file: "{output_folder}/ux-design-specification.md"
 color_themes_html: "{output_folder}/ux-color-themes.html"
 design_directions_html: "{output_folder}/ux-design-directions.html"
 
 standalone: true
+
+# Web bundle configuration for standalone deployment
+web_bundle:
+  name: "create-ux-design"
+  description: "Collaborative UX design facilitation workflow that creates exceptional user experiences through visual exploration and informed decision-making. Unlike template-driven approaches, this workflow facilitates discovery, generates visual options, and collaboratively designs the UX with the user at every step."
+  author: "BMad"
+
+  # Core workflow files ({bmad_folder}/-relative paths)
+  instructions: "{bmad_folder}/bmm/workflows/2-plan-workflows/create-ux-design/instructions.md"
+  validation: "{bmad_folder}/bmm/workflows/2-plan-workflows/create-ux-design/checklist.md"
+  template: "{bmad_folder}/bmm/workflows/2-plan-workflows/create-ux-design/ux-design-template.md"
+
+  # Default configuration values (can be overridden during bundle setup)
+  defaults:
+    user_name: "User"
+    communication_language: "English"
+    document_output_language: "English"
+    user_skill_level: "intermediate"
+    output_folder: "./output"
+
+  # Input/output configuration for web deployment
+  default_output_file: "{output_folder}/ux-design-specification.md"
+  color_themes_html: "{output_folder}/ux-color-themes.html"
+  design_directions_html: "{output_folder}/ux-design-directions.html"
+
+  # Complete file list - ALL files this workflow depends on
+  web_bundle_files:
+    # Core workflow files
+    - "{bmad_folder}/bmm/workflows/2-plan-workflows/create-ux-design/instructions.md"
+    - "{bmad_folder}/bmm/workflows/2-plan-workflows/create-ux-design/checklist.md"
+    - "{bmad_folder}/bmm/workflows/2-plan-workflows/create-ux-design/ux-design-template.md"
+
+    # Task dependencies (referenced in instructions.md)
+    - "{bmad_folder}/core/tasks/workflow.xml"

package/src/modules/bmm/workflows/2-plan-workflows/prd/checklist.md

@@ -1,117 +1,346 @@
-# PRD Workflow Validation Checklist
+# PRD + Epics + Stories Validation Checklist
 
-**Purpose**: Validate PRD workflow outputs are complete, consistent, and ready for next phase.
+**Purpose**: Comprehensive validation that PRD, epics, and stories form a complete, implementable product plan.
 
-**Scope**: Levels 2-4 software projects
+**Scope**: Validates the complete planning output (PRD.md + epics.md) for Levels 2-4 software projects
 
-**Expected Outputs**: PRD.md, epics.md, updated bmm-workflow-status.md
+**Expected Outputs**:
+
+- PRD.md with complete requirements
+- epics.md with detailed epic and story breakdown
+- Updated bmm-workflow-status.yaml
 
 ---
 
-## 1. Output Files Exist
+## 1. PRD Document Completeness
+
+### Core Sections Present
+
+- [ ] Executive Summary with vision alignment
+- [ ] Product differentiator clearly articulated
+- [ ] Project classification (type, domain, complexity)
+- [ ] Success criteria defined
+- [ ] Product scope (MVP, Growth, Vision) clearly delineated
+- [ ] Functional requirements comprehensive and numbered
+- [ ] Non-functional requirements (when applicable)
+- [ ] References section with source documents
+
+### Project-Specific Sections
 
-- [ ] PRD.md created in output folder
-- [ ] epics.md created in output folder (separate file)
-- [ ] bmm-workflow-status.md updated
-- [ ] No unfilled {{template_variables}}
+- [ ] **If complex domain:** Domain context and considerations documented
+- [ ] **If innovation:** Innovation patterns and validation approach documented
+- [ ] **If API/Backend:** Endpoint specification and authentication model included
+- [ ] **If Mobile:** Platform requirements and device features documented
+- [ ] **If SaaS B2B:** Tenant model and permission matrix included
+- [ ] **If UI exists:** UX principles and key interactions documented
+
+### Quality Checks
+
+- [ ] No unfilled template variables ({{variable}})
+- [ ] All variables properly populated with meaningful content
+- [ ] Product differentiator reflected throughout (not just stated once)
+- [ ] Language is clear, specific, and measurable
+- [ ] Project type correctly identified and sections match
+- [ ] Domain complexity appropriately addressed
 
 ---
 
-## 2. PRD.md Core Quality
+## 2. Functional Requirements Quality
 
-### Requirements Coverage
+### FR Format and Structure
 
-- [ ] Functional requirements describe WHAT capabilities (not HOW to implement)
-- [ ] Each FR has unique identifier (FR001, FR002, etc.)
-- [ ] Non-functional requirements (if any) have business justification
-- [ ] Requirements are testable and verifiable
+- [ ] Each FR has unique identifier (FR-001, FR-002, etc.)
+- [ ] FRs describe WHAT capabilities, not HOW to implement
+- [ ] FRs are specific and measurable
+- [ ] FRs are testable and verifiable
+- [ ] FRs focus on user/business value
+- [ ] No technical implementation details in FRs (those belong in architecture)
 
-### User Journeys
+### FR Completeness
 
-- [ ] User journeys reference specific FR numbers
-- [ ] Journeys show complete user paths through system
-- [ ] Success outcomes are clear
+- [ ] All MVP scope features have corresponding FRs
+- [ ] Growth features documented (even if deferred)
+- [ ] Vision features captured for future reference
+- [ ] Domain-mandated requirements included
+- [ ] Innovation requirements captured with validation needs
+- [ ] Project-type specific requirements complete
 
-### Strategic Focus
+### FR Organization
 
-- [ ] PRD focuses on WHAT and WHY (not technical HOW)
-- [ ] No specific technology choices in PRD (those belong in technical-decisions.md)
-- [ ] Goals are outcome-focused, not implementation-focused
+- [ ] FRs organized by capability/feature area (not by tech stack)
+- [ ] Related FRs grouped logically
+- [ ] Dependencies between FRs noted when critical
+- [ ] Priority/phase indicated (MVP vs Growth vs Vision)
 
 ---
 
-## 3. epics.md Story Quality
+## 3. Epics Document Completeness
+
+### Required Files
+
+- [ ] epics.md exists in output folder
+- [ ] Epic list in PRD.md matches epics in epics.md (titles and count)
+- [ ] All epics have detailed breakdown sections
 
-### Story Format
+### Epic Quality
 
-- [ ] All stories follow user story format: "As a [role], I want [capability], so that [benefit]"
+- [ ] Each epic has clear goal and value proposition
+- [ ] Each epic includes complete story breakdown
+- [ ] Stories follow proper user story format: "As a [role], I want [goal], so that [benefit]"
 - [ ] Each story has numbered acceptance criteria
-- [ ] Prerequisites/dependencies explicitly stated
+- [ ] Prerequisites/dependencies explicitly stated per story
+- [ ] Stories are AI-agent sized (completable in 2-4 hour session)
+
+---
 
-### Story Sequencing (CRITICAL)
+## 4. FR Coverage Validation (CRITICAL)
 
-- [ ] **Epic 1 establishes foundation** (infrastructure, initial deployable functionality)
-  - Exception noted if adding to existing app
-- [ ] **Vertical slices**: Each story delivers complete, testable functionality (not horizontal layers)
-- [ ] **No forward dependencies**: No story depends on work from a LATER story or epic
-- [ ] Stories are sequentially ordered within each epic
-- [ ] Each story leaves system in working state
+### Complete Traceability
 
-### Coverage
+- [ ] **Every FR from PRD.md is covered by at least one story in epics.md**
+- [ ] Each story references relevant FR numbers
+- [ ] No orphaned FRs (requirements without stories)
+- [ ] No orphaned stories (stories without FR connection)
+- [ ] Coverage matrix verified (can trace FR → Epic → Stories)
 
-- [ ] All FRs from PRD.md are covered by stories in epics.md
-- [ ] Epic list in PRD.md matches epics in epics.md (titles and count)
+### Coverage Quality
+
+- [ ] Stories sufficiently decompose FRs into implementable units
+- [ ] Complex FRs broken into multiple stories appropriately
+- [ ] Simple FRs have appropriately scoped single stories
+- [ ] Non-functional requirements reflected in story acceptance criteria
+- [ ] Domain requirements embedded in relevant stories
+
+---
+
+## 5. Story Sequencing Validation (CRITICAL)
+
+### Epic 1 Foundation Check
+
+- [ ] **Epic 1 establishes foundational infrastructure**
+- [ ] Epic 1 delivers initial deployable functionality
+- [ ] Epic 1 creates baseline for subsequent epics
+- [ ] Exception: If adding to existing app, foundation requirement adapted appropriately
+
+### Vertical Slicing
+
+- [ ] **Each story delivers complete, testable functionality** (not horizontal layers)
+- [ ] No "build database" or "create UI" stories in isolation
+- [ ] Stories integrate across stack (data + logic + presentation when applicable)
+- [ ] Each story leaves system in working/deployable state
+
+### No Forward Dependencies
+
+- [ ] **No story depends on work from a LATER story or epic**
+- [ ] Stories within each epic are sequentially ordered
+- [ ] Each story builds only on previous work
+- [ ] Dependencies flow backward only (can reference earlier stories)
+- [ ] Parallel tracks clearly indicated if stories are independent
+
+### Value Delivery Path
+
+- [ ] Each epic delivers significant end-to-end value
+- [ ] Epic sequence shows logical product evolution
+- [ ] User can see value after each epic completion
+- [ ] MVP scope clearly achieved by end of designated epics
+
+---
+
+## 6. Scope Management
+
+### MVP Discipline
+
+- [ ] MVP scope is genuinely minimal and viable
+- [ ] Core features list contains only true must-haves
+- [ ] Each MVP feature has clear rationale for inclusion
+- [ ] No obvious scope creep in "must-have" list
+
+### Future Work Captured
+
+- [ ] Growth features documented for post-MVP
+- [ ] Vision features captured to maintain long-term direction
+- [ ] Out-of-scope items explicitly listed
+- [ ] Deferred features have clear reasoning for deferral
+
+### Clear Boundaries
+
+- [ ] Stories marked as MVP vs Growth vs Vision
+- [ ] Epic sequencing aligns with MVP → Growth progression
+- [ ] No confusion about what's in vs out of initial scope
+
+---
+
+## 7. Research and Context Integration
+
+### Source Document Integration
+
+- [ ] **If product brief exists:** Key insights incorporated into PRD
+- [ ] **If domain brief exists:** Domain requirements reflected in FRs and stories
+- [ ] **If research documents exist:** Research findings inform requirements
+- [ ] **If competitive analysis exists:** Differentiation strategy clear in PRD
+- [ ] All source documents referenced in PRD References section
+
+### Research Continuity to Architecture
+
+- [ ] Domain complexity considerations documented for architects
+- [ ] Technical constraints from research captured
+- [ ] Regulatory/compliance requirements clearly stated
+- [ ] Integration requirements with existing systems documented
+- [ ] Performance/scale requirements informed by research data
+
+### Information Completeness for Next Phase
+
+- [ ] PRD provides sufficient context for architecture decisions
+- [ ] Epics provide sufficient detail for technical design
+- [ ] Stories have enough acceptance criteria for implementation
+- [ ] Non-obvious business rules documented
+- [ ] Edge cases and special scenarios captured
 
 ---
 
-## 4. Cross-Document Consistency
+## 8. Cross-Document Consistency
+
+### Terminology Consistency
 
-- [ ] Epic titles consistent between PRD.md and epics.md
-- [ ] FR references in user journeys exist in requirements section
-- [ ] Terminology consistent across documents
+- [ ] Same terms used across PRD and epics for concepts
+- [ ] Feature names consistent between documents
+- [ ] Epic titles match between PRD and epics.md
 - [ ] No contradictions between PRD and epics
 
+### Alignment Checks
+
+- [ ] Success metrics in PRD align with story outcomes
+- [ ] Product differentiator articulated in PRD reflected in epic goals
+- [ ] Technical preferences in PRD align with story implementation hints
+- [ ] Scope boundaries consistent across all documents
+
 ---
 
-## 5. Readiness for Next Phase
+## 9. Readiness for Implementation
+
+### Architecture Readiness (Next Phase)
+
+- [ ] PRD provides sufficient context for architecture workflow
+- [ ] Technical constraints and preferences documented
+- [ ] Integration points identified
+- [ ] Performance/scale requirements specified
+- [ ] Security and compliance needs clear
 
-**Adapt based on project level from bmm-workflow-status.md:**
+### Development Readiness
 
-### If Level 2:
+- [ ] Stories are specific enough to estimate
+- [ ] Acceptance criteria are testable
+- [ ] Technical unknowns identified and flagged
+- [ ] Dependencies on external systems documented
+- [ ] Data requirements specified
 
-- [ ] PRD provides sufficient context for tech-spec workflow (lightweight solutioning)
-- [ ] Epic structure supports 5-15 story implementation scope
+### Track-Appropriate Detail
 
-### If Level 3-4:
+**If BMad Method:**
 
-- [ ] PRD provides sufficient context for create-architecture workflow
-- [ ] Epic structure supports phased delivery approach
-- [ ] Clear value delivery path through epic sequence
+- [ ] PRD supports full architecture workflow
+- [ ] Epic structure supports phased delivery
+- [ ] Scope appropriate for product/platform development
+- [ ] Clear value delivery through epic sequence
+
+**If Enterprise Method:**
+
+- [ ] PRD addresses enterprise requirements (security, compliance, multi-tenancy)
+- [ ] Epic structure supports extended planning phases
+- [ ] Scope includes security, devops, and test strategy considerations
+- [ ] Clear value delivery with enterprise gates
 
 ---
 
-## 6. Critical Failures (Auto-Fail)
+## 10. Quality and Polish
+
+### Writing Quality
+
+- [ ] Language is clear and free of jargon (or jargon is defined)
+- [ ] Sentences are concise and specific
+- [ ] No vague statements ("should be fast", "user-friendly")
+- [ ] Measurable criteria used throughout
+- [ ] Professional tone appropriate for stakeholder review
+
+### Document Structure
+
+- [ ] Sections flow logically
+- [ ] Headers and numbering consistent
+- [ ] Cross-references accurate (FR numbers, section references)
+- [ ] Formatting consistent throughout
+- [ ] Tables/lists formatted properly
+
+### Completeness Indicators
+
+- [ ] No [TODO] or [TBD] markers remain
+- [ ] No placeholder text
+- [ ] All sections have substantive content
+- [ ] Optional sections either complete or omitted (not half-done)
 
-- [ ] ❌ **No epics.md file** (two-file output is required)
-- [ ] ❌ **Epic 1 doesn't establish foundation** (violates core principle)
-- [ ] ❌ **Stories have forward dependencies** (would break sequential implementation)
+---
+
+## Critical Failures (Auto-Fail)
+
+If ANY of these are true, validation FAILS:
+
+- [ ] ❌ **No epics.md file exists** (two-file output required)
+- [ ] ❌ **Epic 1 doesn't establish foundation** (violates core sequencing principle)
+- [ ] ❌ **Stories have forward dependencies** (breaks sequential implementation)
 - [ ] ❌ **Stories not vertically sliced** (horizontal layers block value delivery)
-- [ ] ❌ **Technical decisions in PRD** (should be in technical-decisions.md)
 - [ ] ❌ **Epics don't cover all FRs** (orphaned requirements)
-- [ ] ❌ **User journeys don't reference FR numbers** (missing traceability)
+- [ ] ❌ **FRs contain technical implementation details** (should be in architecture)
+- [ ] ❌ **No FR traceability to stories** (can't validate coverage)
+- [ ] ❌ **Template variables unfilled** (incomplete document)
 
 ---
 
-## Validation Notes
+## Validation Summary
 
-**Document any findings:**
+- **Pass Rate ≥ 95%:** ✅ EXCELLENT - Ready for architecture phase
+- **Pass Rate 85-94%:** ⚠️ GOOD - Minor fixes needed
+- **Pass Rate 70-84%:** ⚠️ FAIR - Important issues to address
+- **Pass Rate < 70%:** ❌ POOR - Significant rework required
 
-- Strengths:
-- Issues to address:
-- Recommended actions:
+### Critical Issue Threshold
+
+- **0 Critical Failures:** Proceed to fixes
+- **1+ Critical Failures:** STOP - Must fix critical issues first
+
+---
 
-**Ready for next phase?** [Yes / No - explain]
+## Validation Execution Notes
+
+**When validating:**
+
+1. **Load ALL documents - whole or sharded (but not both of each) for example epics.md vs epics/\*.md:**
+   - PRD.md (required)
+   - epics.md (required)
+   - product-brief.md (if exists)
+   - domain-brief.md (if exists)
+   - research documents (if referenced)
+
+2. **Validate in order:**
+   - Check critical failures first (immediate stop if any found)
+   - Verify PRD completeness
+   - Verify epics completeness
+   - Cross-reference FR coverage (most important)
+   - Check sequencing (second most important)
+   - Validate research integration
+   - Check polish and quality
+
+3. **Report findings:**
+   - List critical failures prominently
+   - Group issues by severity
+   - Provide specific line numbers/sections
+   - Suggest concrete fixes
+   - Highlight what's working well
+
+4. **Provide actionable next steps:**
+   - If validation passes: "Ready for architecture workflow"
+   - If minor issues: "Fix [X] items then re-validate"
+   - If major issues: "Rework [sections] then re-validate"
+   - If critical failures: "Must fix critical items before proceeding"
 
 ---
 
-_Adapt this checklist based on actual outputs. Not all sections may apply to every project._
+**Remember:** This validation ensures the entire planning phase is complete and the implementation phase has everything needed to succeed. Be thorough but fair - the goal is quality, not perfection.

package/src/modules/bmm/workflows/2-plan-workflows/prd/domain-complexity.csv

@@ -0,0 +1,13 @@
+domain,signals,complexity,key_concerns,required_knowledge,suggested_workflow,web_searches,special_sections
+healthcare,"medical,diagnostic,clinical,FDA,patient,treatment,HIPAA,therapy,pharma,drug",high,"FDA approval;Clinical validation;HIPAA compliance;Patient safety;Medical device classification;Liability","Regulatory pathways;Clinical trial design;Medical standards;Data privacy;Integration requirements","domain-research","FDA software medical device guidance {date};HIPAA compliance software requirements;Medical software standards {date};Clinical validation software","clinical_requirements;regulatory_pathway;validation_methodology;safety_measures"
+fintech,"payment,banking,trading,investment,crypto,wallet,transaction,KYC,AML,funds,fintech",high,"Regional compliance;Security standards;Audit requirements;Fraud prevention;Data protection","KYC/AML requirements;PCI DSS;Open banking;Regional laws (US/EU/APAC);Crypto regulations","domain-research","fintech regulations {date};payment processing compliance {date};open banking API standards;cryptocurrency regulations {date}","compliance_matrix;security_architecture;audit_requirements;fraud_prevention"
+govtech,"government,federal,civic,public sector,citizen,municipal,voting",high,"Procurement rules;Security clearance;Accessibility (508);FedRAMP;Privacy;Transparency","Government procurement;Security frameworks;Accessibility standards;Privacy laws;Open data requirements","domain-research","government software procurement {date};FedRAMP compliance requirements;section 508 accessibility;government security standards","procurement_compliance;security_clearance;accessibility_standards;transparency_requirements"
+edtech,"education,learning,student,teacher,curriculum,assessment,K-12,university,LMS",medium,"Student privacy (COPPA/FERPA);Accessibility;Content moderation;Age verification;Curriculum standards","Educational privacy laws;Learning standards;Accessibility requirements;Content guidelines;Assessment validity","domain-research","educational software privacy {date};COPPA FERPA compliance;WCAG education requirements;learning management standards","privacy_compliance;content_guidelines;accessibility_features;curriculum_alignment"
+aerospace,"aircraft,spacecraft,aviation,drone,satellite,propulsion,flight,radar,navigation",high,"Safety certification;DO-178C compliance;Performance validation;Simulation accuracy;Export controls","Aviation standards;Safety analysis;Simulation validation;ITAR/export controls;Performance requirements","domain-research + technical-model","DO-178C software certification;aerospace simulation standards {date};ITAR export controls software;aviation safety requirements","safety_certification;simulation_validation;performance_requirements;export_compliance"
+automotive,"vehicle,car,autonomous,ADAS,automotive,driving,EV,charging",high,"Safety standards;ISO 26262;V2X communication;Real-time requirements;Certification","Automotive standards;Functional safety;V2X protocols;Real-time systems;Testing requirements","domain-research","ISO 26262 automotive software;automotive safety standards {date};V2X communication protocols;EV charging standards","safety_standards;functional_safety;communication_protocols;certification_requirements"
+scientific,"research,algorithm,simulation,modeling,computational,analysis,data science,ML,AI",medium,"Reproducibility;Validation methodology;Peer review;Performance;Accuracy;Computational resources","Scientific method;Statistical validity;Computational requirements;Domain expertise;Publication standards","technical-model","scientific computing best practices {date};research reproducibility standards;computational modeling validation;peer review software","validation_methodology;accuracy_metrics;reproducibility_plan;computational_requirements"
+legaltech,"legal,law,contract,compliance,litigation,patent,attorney,court",high,"Legal ethics;Bar regulations;Data retention;Attorney-client privilege;Court system integration","Legal practice rules;Ethics requirements;Court filing systems;Document standards;Confidentiality","domain-research","legal technology ethics {date};law practice management software requirements;court filing system standards;attorney client privilege technology","ethics_compliance;data_retention;confidentiality_measures;court_integration"
+insuretech,"insurance,claims,underwriting,actuarial,policy,risk,premium",high,"Insurance regulations;Actuarial standards;Data privacy;Fraud detection;State compliance","Insurance regulations by state;Actuarial methods;Risk modeling;Claims processing;Regulatory reporting","domain-research","insurance software regulations {date};actuarial standards software;insurance fraud detection;state insurance compliance","regulatory_requirements;risk_modeling;fraud_detection;reporting_compliance"
+energy,"energy,utility,grid,solar,wind,power,electricity,oil,gas",high,"Grid compliance;NERC standards;Environmental regulations;Safety requirements;Real-time operations","Energy regulations;Grid standards;Environmental compliance;Safety protocols;SCADA systems","domain-research","energy sector software compliance {date};NERC CIP standards;smart grid requirements;renewable energy software standards","grid_compliance;safety_protocols;environmental_compliance;operational_requirements"
+gaming,"game,player,gameplay,level,character,multiplayer,quest",redirect,"REDIRECT TO GAME WORKFLOWS","Game design","game-brief","NA","NA"
+general,"",low,"Standard requirements;Basic security;User experience;Performance","General software practices","continue","software development best practices {date}","standard_requirements"