mirror of
https://github.com/bmadcode/BMAD-METHOD.git
synced 2025-12-29 16:14:59 +00:00
3d4ea5ffd2
Implement comprehensive document sharding system across all BMM workflows enabling 90%+ token savings for large multi-epic projects through selective loading optimization.
## Document Sharding System
### Core Features
- **Universal Support**: All 12 BMM workflows (Phase 1-4) handle both whole and sharded documents
- **Dual Loading Strategy**: Full Load (Phase 1-3) vs Selective Load (Phase 4)
- **Automatic Discovery**: Workflows detect format transparently (whole → sharded priority)
- **Efficiency Optimization**: 90%+ token reduction for 10+ epic projects in Phase 4
### Implementation Details
**Phase 1-3 Workflows (7 workflows) - Full Load Strategy:**
- product-brief, prd, gdd, create-ux-design, tech-spec, architecture, solutioning-gate-check
- Load entire sharded documents when present
- Transparent to user experience
- Better organization for large projects
**Phase 4 Workflows (5 workflows) - Selective Load Strategy:**
- sprint-planning (Full Load exception - needs all epics)
- epic-tech-context, create-story, story-context, code-review (Selective Load)
- Load ONLY the specific epic needed (e.g., epic-3.md for Epic 3 stories)
- Massive efficiency: Skip loading 9 other epics in 10-epic project
### Workflow Enhancements
**Added to all workflows:**
- `input_file_patterns` in workflow.yaml with wildcard discovery
- Document Discovery section in instructions.md
- Support for sharded index + section files
- Brownfield `docs/index.md` support
**Pattern standardization:**
```yaml
input_file_patterns:
document:
whole: "{output_folder}/*doc*.md"
sharded: "{output_folder}/*doc*/index.md"
sharded_single: "{output_folder}/*doc*/section-{{id}}.md" # Selective load
```
### Retrospective Workflow Major Overhaul
Transformed retrospective into immersive, interactive team experience:
**Epic Discovery Priority (Fixed):**
- Priority 1: Check sprint-status.yaml for last completed epic
- Priority 2: Ask user directly
- Priority 3: Scan stories folder (last resort)
**New Capabilities:**
- Deep story analysis: Extract dev notes, mistakes, review feedback, lessons learned
- Previous retro integration: Track action items, verify lessons applied
- Significant change detection: Alert when discoveries require epic updates
- Intent-based facilitation: Natural conversation vs scripted phrases
- Party mode protocol: Clear speaker identification (Name (Role): dialogue)
- Team dynamics: Drama, disagreements, diverse perspectives, authentic conflict
**Structure:**
- 12 whole-number steps (no decimals)
- Highly interactive with constant user engagement
- Cross-references previous retro for accountability
- Synthesizes patterns across all stories
- Detects architectural assumption changes
## Documentation
**Created:**
- `docs/document-sharding-guide.md` - Comprehensive 300+ line guide
- What is sharding, when to use it (token thresholds)
- How sharding works (discovery system, loading strategies)
- Using shard-doc tool
- Full Load vs Selective Load patterns
- Complete examples and troubleshooting
- Custom workflow integration patterns
**Updated:**
- `README.md` - Added Document Sharding feature section
- `docs/index.md` - Added under Advanced Topics → Optimization
- `src/modules/bmm/workflows/README.md` - Added sharding section with usage
- `src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md` - Added complete implementation patterns for workflow builders
**Documentation levels:**
1. Overview (README.md) - Quick feature highlight
2. User guide (BMM workflows README) - Practical usage
3. Reference (document-sharding-guide.md) - Complete details
4. Builder guide (workflow-creation-guide.md) - Implementation patterns
## Efficiency Gains
**Example: 10-Epic Project**
Before sharding:
- epic-tech-context for Epic 3: Load all 10 epics (~50k tokens)
- create-story for Epic 3: Load all 10 epics (~50k tokens)
- story-context for Epic 3: Load all 10 epics (~50k tokens)
After sharding with selective load:
- epic-tech-context for Epic 3: Load Epic 3 only (~5k tokens) = 90% reduction
- create-story for Epic 3: Load Epic 3 only (~5k tokens) = 90% reduction
- story-context for Epic 3: Load Epic 3 only (~5k tokens) = 90% reduction
## Breaking Changes
None - fully backward compatible. Workflows work with existing whole documents.
## Files Changed
**Workflows Updated (25 files):**
- 7 Phase 1-3 workflows: Added full load sharding support
- 5 Phase 4 workflows: Added selective load sharding support
- 1 retrospective workflow: Complete overhaul with sharding support
**Documentation (5 files):**
- Created: document-sharding-guide.md
- Updated: README.md, docs/index.md, BMM workflows README, BMB workflow-creation-guide
- Removed: Old conversion report (obsolete)
## Future Extensibility
- BMB workflows now aware of sharding patterns
- Custom modules can easily implement sharding support
- Standard patterns documented for consistency
- No need to explain concept in future development
Implementation Ready Check Workflow
Overview
The Implementation Ready Check workflow provides a systematic validation of all planning and solutioning artifacts before transitioning from Phase 3 (Solutioning) to Phase 4 (Implementation) in the BMad Method. This workflow ensures that PRDs, architecture documents, and story breakdowns are properly aligned with no critical gaps or contradictions.
Purpose
This workflow is designed to:
- Validate Completeness: Ensure all required planning documents exist and are complete
- Verify Alignment: Check that PRD, architecture, and stories are cohesive and aligned
- Identify Gaps: Detect missing stories, unaddressed requirements, or sequencing issues
- Assess Risks: Find contradictions, conflicts, or potential implementation blockers
- Provide Confidence: Give teams confidence that planning is solid before starting development
When to Use
This workflow should be invoked:
- At the end of Phase 3 (Solutioning) for Level 2-4 projects
- Before beginning Phase 4 (Implementation)
- After significant planning updates or architectural changes
- When validating readiness for Level 0-1 projects (simplified validation)
Project Level Adaptations
The workflow adapts its validation based on project level:
Level 0-1 Projects
- Validates tech spec and simple stories only
- Checks internal consistency and basic coverage
- Lighter validation appropriate for simple projects
Level 2 Projects
- Validates PRD, tech spec (with embedded architecture), and stories
- Ensures PRD requirements are fully covered
- Verifies technical approach aligns with business goals
Level 3-4 Projects
- Full validation of PRD, architecture document, and comprehensive stories
- Deep cross-reference checking across all artifacts
- Validates architectural decisions don't introduce scope creep
- Checks UX artifacts if applicable
How to Invoke
Via Scrum Master Agent
*solutioning-gate-check
Direct Workflow Invocation
workflow solutioning-gate-check
Expected Inputs
The workflow will automatically search your project's output folder for:
- Product Requirements Documents (PRD)
- Architecture documents
- Technical Specifications
- Epic and Story breakdowns
- UX artifacts (if applicable)
No manual input file specification needed - the workflow discovers documents automatically.
Generated Output
The workflow produces a comprehensive Implementation Readiness Report containing:
- Executive Summary - Overall readiness status
- Document Inventory - What was found and reviewed
- Alignment Validation - Cross-reference analysis results
- Gap Analysis - Missing items and risks identified
- Findings by Severity - Critical, High, Medium, Low issues
- Recommendations - Specific actions to address issues
- Readiness Decision - Ready, Ready with Conditions, or Not Ready
Output Location: {output_folder}/implementation-readiness-report-{date}.md
Workflow Steps
- Initialize - Get current workflow status and project level
- Document Discovery - Find all planning artifacts
- Deep Analysis - Extract requirements, decisions, and stories
- Cross-Reference Validation - Check alignment between all documents
- Gap and Risk Analysis - Identify issues and conflicts
- UX Validation (optional) - Verify UX concerns are addressed
- Generate Report - Compile comprehensive readiness assessment
- Status Update (optional) - Offer to advance workflow to next phase
Validation Criteria
The workflow uses systematic validation rules adapted to each project level:
- Document completeness and quality
- Requirement to story traceability
- Architecture to implementation alignment
- Story sequencing and dependencies
- Greenfield project setup coverage
- Risk identification and mitigation
For projects using the new architecture workflow (decision-architecture.md), additional validations include:
- Implementation patterns defined for consistency
- Technology versions verified and current
- Starter template initialization as first story
- UX specification alignment (if provided)
Special Features
Intelligent Adaptation
- Automatically adjusts validation based on project level
- Recognizes when UX workflow is active
- Handles greenfield vs. brownfield projects differently
Comprehensive Coverage
- Validates not just presence but quality and alignment
- Checks for both gaps and gold-plating
- Ensures logical story sequencing
Actionable Output
- Provides specific, actionable recommendations
- Categorizes issues by severity
- Includes positive findings and commendations
Integration with BMad Method
This workflow integrates seamlessly with the BMad Method workflow system:
- Uses workflow-status to understand project context
- Can update workflow status to advance to next phase
- Follows standard BMad document naming conventions
- Searches standard output folders automatically
Troubleshooting
Documents Not Found
- Ensure documents are in the configured output folder
- Check that document names follow BMad conventions
- Verify workflow-status is properly configured
Validation Too Strict
- The workflow adapts to project level automatically
- Level 0-1 projects get lighter validation
- Consider if your project level is set correctly
Report Too Long
- Focus on Critical and High priority issues first
- Use the executive summary for quick decisions
- Review detailed findings only for areas of concern
Support
For issues or questions about this workflow:
- Consult the BMad Method documentation
- Check the SM agent for workflow guidance
- Review validation-criteria.yaml for detailed rules
This workflow is part of the BMad Method v6-alpha suite of planning and solutioning tools