From 5e1149dc14474dc0161f11b24c6335d02c71f445 Mon Sep 17 00:00:00 2001 From: Nikolas Hor <116851567+nikolasdehor@users.noreply.github.com> Date: Thu, 12 Mar 2026 00:39:31 -0300 Subject: [PATCH] fix: consume UX Design Specification as first-class input in create-epics-and-stories (#1909) The create-epics-and-stories workflow previously relegated UX Design requirements to a vague "Additional Requirements" list, causing actionable UX work items (design tokens, component proposals, accessibility audits) to be silently dropped from the epic/story breakdown. Changes: - step-01: Elevate UX Design extraction to first-class with dedicated UX-DR identifiers and thorough extraction guidance - step-03: Add UX Design integration guidance for story creation and final validation coverage check - epics-template: Add dedicated UX Design Requirements section Co-authored-by: Brian --- .../steps/step-01-validate-prerequisites.md | 42 +++++++++++++------ .../steps/step-03-create-stories.md | 6 ++- .../templates/epics-template.md | 4 ++ 3 files changed, 39 insertions(+), 13 deletions(-) diff --git a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-01-validate-prerequisites.md b/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-01-validate-prerequisites.md index 5d2b0add9..2d50ecc32 100644 --- a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-01-validate-prerequisites.md +++ b/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-01-validate-prerequisites.md @@ -154,20 +154,31 @@ Review the Architecture document for technical requirements that impact epic and ... ``` -### 6. Extract Additional Requirements from UX (if exists) +### 6. Extract UX Design Requirements (if UX document exists) -Review the UX document for requirements that affect epic and story creation: +**IMPORTANT**: The UX Design Specification is a first-class input document, not supplementary material. Requirements from the UX spec must be extracted with the same rigor as PRD functional requirements. + +Read the FULL UX Design document and extract ALL actionable work items: **Look for:** -- Responsive design requirements -- Accessibility requirements -- Browser/device compatibility -- User interaction patterns that need implementation -- Animation or transition requirements -- Error handling UX requirements +- **Design token work**: Color systems, spacing scales, typography tokens that need implementation or consolidation +- **Component proposals**: Reusable UI components identified in the UX spec (e.g., ConfirmActions, StatusMessage, EmptyState, FocusIndicator) +- **Visual standardization**: Semantic CSS classes, consistent color palette usage, design pattern consolidation +- **Accessibility requirements**: Contrast audit fixes, ARIA patterns, keyboard navigation, screen reader support +- **Responsive design requirements**: Breakpoints, layout adaptations, mobile-specific interactions +- **Interaction patterns**: Animations, transitions, loading states, error handling UX +- **Browser/device compatibility**: Target platforms, progressive enhancement requirements -**Add these to Additional Requirements list.** +**Format UX Design Requirements as a SEPARATE section (not merged into Additional Requirements):** + +``` +UX-DR1: [Actionable UX design requirement with clear implementation scope] +UX-DR2: [Actionable UX design requirement with clear implementation scope] +... +``` + +**🚨 CRITICAL**: Do NOT reduce UX requirements to vague summaries. Each UX-DR must be specific enough to generate a story with testable acceptance criteria. If the UX spec identifies 6 reusable components, list all 6 — not "create reusable components." ### 7. Load and Initialize Template @@ -178,7 +189,8 @@ Load {epicsTemplate} and initialize {outputFile}: 3. Replace placeholder sections with extracted requirements: - {{fr_list}} → extracted FRs - {{nfr_list}} → extracted NFRs - - {{additional_requirements}} → extracted additional requirements + - {{additional_requirements}} → extracted additional requirements (from Architecture) + - {{ux_design_requirements}} → extracted UX Design Requirements (if UX document exists) 4. Leave {{requirements_coverage_map}} and {{epics_list}} as placeholders for now ### 8. Present Extracted Requirements @@ -197,12 +209,17 @@ Display to user: - Display key NFRs - Ask if any constraints were missed -**Additional Requirements:** +**Additional Requirements (Architecture):** - Summarize technical requirements from Architecture -- Summarize UX requirements (if applicable) - Verify completeness +**UX Design Requirements (if applicable):** + +- Show count of UX-DRs found +- Display key UX Design requirements (design tokens, components, accessibility) +- Verify each UX-DR is specific enough for story creation + ### 9. Get User Confirmation Ask: "Do these extracted requirements accurately represent what needs to be built? Any additions or corrections?" @@ -216,6 +233,7 @@ After extraction and confirmation, update {outputFile} with: - Complete FR list in {{fr_list}} section - Complete NFR list in {{nfr_list}} section - All additional requirements in {{additional_requirements}} section +- UX Design requirements in {{ux_design_requirements}} section (if UX document exists) ### 10. Present MENU OPTIONS diff --git a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-03-create-stories.md b/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-03-create-stories.md index 07e666e03..8f413dbc9 100644 --- a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-03-create-stories.md +++ b/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-03-create-stories.md @@ -66,9 +66,11 @@ Load {outputFile} and review: - Approved epics_list from Step 2 - FR coverage map -- All requirements (FRs, NFRs, additional) +- All requirements (FRs, NFRs, additional, **UX Design requirements if present**) - Template structure at the end of the document +**UX Design Integration**: If UX Design Requirements (UX-DRs) were extracted in Step 1, ensure they are visible during story creation. UX-DRs must be covered by stories — either within existing epics (e.g., accessibility fixes for a feature epic) or in a dedicated "Design System / UX Polish" epic. + ### 2. Explain Story Creation Approach **STORY CREATION GUIDELINES:** @@ -146,6 +148,7 @@ Display: - Epic goal statement - FRs covered by this epic - Any NFRs or additional requirements relevant +- Any UX Design Requirements (UX-DRs) relevant to this epic #### B. Story Breakdown @@ -207,6 +210,7 @@ After all epics and stories are generated: - Verify the document follows template structure exactly - Ensure all placeholders are replaced - Confirm all FRs are covered +- **Confirm all UX Design Requirements (UX-DRs) are covered by at least one story** (if UX document was an input) - Check formatting consistency ## TEMPLATE STRUCTURE COMPLIANCE: diff --git a/src/bmm/workflows/3-solutioning/create-epics-and-stories/templates/epics-template.md b/src/bmm/workflows/3-solutioning/create-epics-and-stories/templates/epics-template.md index 05afe1f5f..bf80c7fba 100644 --- a/src/bmm/workflows/3-solutioning/create-epics-and-stories/templates/epics-template.md +++ b/src/bmm/workflows/3-solutioning/create-epics-and-stories/templates/epics-template.md @@ -23,6 +23,10 @@ This document provides the complete epic and story breakdown for {{project_name} {{additional_requirements}} +### UX Design Requirements + +{{ux_design_requirements}} + ### FR Coverage Map {{requirements_coverage_map}}