diff --git a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md b/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md index 6453c62ee..def6ff8ab 100644 --- a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md +++ b/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md @@ -76,7 +76,8 @@ Load {outputFile} and review: 2. **Requirements Grouping**: Group related FRs that deliver cohesive user outcomes 3. **Incremental Delivery**: Each epic should deliver value independently 4. **Logical Flow**: Natural progression from user's perspective -5. **🔗 Dependency-Free Within Epic**: Stories within an epic must NOT depend on future stories +5. **Dependency-Free Within Epic**: Stories within an epic must NOT depend on future stories +6. **Implementation Efficiency**: Consider consolidating epics that all modify the same core files into fewer epics **⚠️ CRITICAL PRINCIPLE:** Organize by USER VALUE, not technical layers: @@ -95,6 +96,18 @@ Organize by USER VALUE, not technical layers: - Epic 3: Frontend Components (creates reusable components) - **No user value** - Epic 4: Deployment Pipeline (CI/CD setup) - **No user value** +**❌ WRONG Epic Examples (File Churn on Same Component):** + +- Epic 1: File Upload (modifies model, controller, web form, web API) +- Epic 2: File Status (modifies model, controller, web form, web API) +- Epic 3: File Access permissions (modifies model, controller, web form, web API) +- All three epics touch the same files — consolidate into one epic with ordered stories + +**✅ CORRECT Alternative:** + +- Epic 1: File Management Enhancement (upload, status, permissions as stories within one epic) +- Rationale: Single component, fully pre-designed, no feedback loop between epics + **🔗 DEPENDENCY RULES:** - Each epic must deliver COMPLETE functionality for its domain @@ -103,21 +116,38 @@ Organize by USER VALUE, not technical layers: ### 3. Design Epic Structure Collaboratively -**Step A: Identify User Value Themes** +**Step A: Assess Context and Identify Themes** + +First, assess how much of the solution design is already validated (Architecture, UX, Test Design). +When the outcome is certain and direction changes between epics are unlikely, prefer fewer but larger epics. +Split into multiple epics when there is a genuine risk boundary or when early feedback could change direction +of following epics. + +Then, identify user value themes: - Look for natural groupings in the FRs - Identify user journeys or workflows - Consider user types and their goals **Step B: Propose Epic Structure** -For each proposed epic: + +For each proposed epic (considering whether epics share the same core files): 1. **Epic Title**: User-centric, value-focused 2. **User Outcome**: What users can accomplish after this epic 3. **FR Coverage**: Which FR numbers this epic addresses 4. **Implementation Notes**: Any technical or UX considerations -**Step C: Create the epics_list** +**Step C: Review for File Overlap** + +Assess whether multiple proposed epics repeatedly target the same core files. If overlap is significant: + +- Distinguish meaningful overlap (same component end-to-end) from incidental sharing +- Ask whether to consolidate into one epic with ordered stories +- If confirmed, merge the epic FRs into a single epic, preserving dependency flow: each story must still fit within + a single dev agent's context + +**Step D: Create the epics_list** Format the epics_list as: diff --git a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md b/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md index 92bb71277..677bac079 100644 --- a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md +++ b/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md @@ -110,6 +110,12 @@ Review the complete epic and story breakdown to ensure EVERY FR is covered: - Dependencies flow naturally - Foundation stories only setup what's needed - No big upfront technical work +- **File Churn Check:** Do multiple epics repeatedly modify the same core files? + - Assess whether the overlap pattern suggests unnecessary churn or is incidental + - If overlap is significant: Validate that splitting provides genuine value (risk mitigation, feedback loops, context size limits) + - If no justification for the split: Recommend consolidation into fewer epics + - ❌ WRONG: Multiple epics each modify the same core files with no feedback loop between them + - ✅ RIGHT: Epics target distinct files/components, OR consolidation was explicitly considered and rejected with rationale ### 5. Dependency Validation (CRITICAL)