External/BMAD-METHOD
1
0
Fork 0
mirror of https://github.com/bmadcode/BMAD-METHOD.git synced 2025-12-29 16:14:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: add universal document sharding support with dual-strategy loading

Browse Source 
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
This commit is contained in:
Brian Madison
2025-11-02 00:13:33 -05:00
parent f77babcd5e
commit 3d4ea5ffd2
32 changed files with 2397 additions and 437 deletions
Download Patch File Download Diff File Expand all files Collapse all files

158
src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md
View File

@@ -1020,6 +1020,164 @@ _Generated on {{date}}_
- **Unclosed check tags** - Always close `<check if="">...</check>` blocks
- **Wrong conditional pattern** - Use `<action if="">` for single items, `<check if="">` for blocks
## Document Sharding Support
If your workflow loads large planning documents (PRDs, epics, architecture, etc.), implement sharding support for efficiency.
### What is Document Sharding?
Document sharding splits large markdown files into smaller section-based files:
- `PRD.md` (50k tokens) → `prd/epic-1.md`, `prd/epic-2.md`, etc.
- Enables selective loading (90%+ token savings)
- All BMM workflows support both whole and sharded documents
### When to Add Sharding Support
**Add sharding support if your workflow:**
- Loads planning documents (PRD, epics, architecture, UX specs)
- May be used in large multi-epic projects
- Processes documents that could exceed 20k tokens
- Would benefit from selective section loading
**Skip sharding support if your workflow:**
- Only generates small documents
- Doesn't load external documents
- Works with code files (not planning docs)
### Implementation Pattern
#### 1. Add input_file_patterns to workflow.yaml
```yaml
# Smart input file references - handles both whole docs and sharded docs
# Priority: Whole document first, then sharded version
input_file_patterns:
prd:
whole: '{output_folder}/*prd*.md'
sharded: '{output_folder}/*prd*/index.md'
epics:
whole: '{output_folder}/*epic*.md'
sharded_index: '{output_folder}/*epic*/index.md'
sharded_single: '{output_folder}/*epic*/epic-{{epic_num}}.md' # For selective load
architecture:
whole: '{output_folder}/*architecture*.md'
sharded: '{output_folder}/*architecture*/index.md'
document_project:
sharded: '{output_folder}/docs/index.md' # Brownfield always uses index
```
#### 2. Add Discovery Instructions to instructions.md
Place early in instructions (after critical declarations, before workflow steps):
```markdown
## 📚 Document Discovery
This workflow requires: [list required documents]
**Discovery Process** (execute for each document):
1. **Search for whole document first** - Use fuzzy file matching
2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md`
3. **If sharded version found**:
- Read `index.md` to understand the document structure
- Read ALL section files listed in the index (or specific sections for selective load)
- Treat the combined content as if it were a single document
4. **Brownfield projects**: The `document-project` workflow creates `{output_folder}/docs/index.md`
**Priority**: If both whole and sharded versions exist, use the whole document.
**Fuzzy matching**: Be flexible with document names - users may use variations.
```
#### 3. Choose Loading Strategy
**Full Load Strategy** (most workflows):
```xml
<action>Search for document using fuzzy pattern: {output_folder}/*prd*.md</action>
<action>If not found, check for sharded version: {output_folder}/*prd*/index.md</action>
<action if="sharded found">Read index.md to understand structure</action>
<action if="sharded found">Read ALL section files listed in index</action>
<action if="sharded found">Combine content as single document</action>
```
**Selective Load Strategy** (advanced - for phase 4 type workflows):
```xml
<action>Determine section needed (e.g., epic_num from story key)</action>
<action>Check for sharded version: {output_folder}/*epics*/index.md</action>
<action if="sharded found">Read ONLY the specific section file: epics/epic-{{epic_num}}.md</action>
<action if="sharded found">Skip all other section files (efficiency optimization)</action>
<action if="whole document found">Load complete document and extract relevant section</action>
```
### Pattern Examples
**Example 1: Simple Full Load**
```yaml
# workflow.yaml
input_file_patterns:
requirements:
whole: '{output_folder}/*requirements*.md'
sharded: '{output_folder}/*requirements*/index.md'
```
```markdown
<!-- instructions.md -->
## Document Discovery
Load requirements document (whole or sharded).
1. Try whole: _requirements_.md
2. If not found, try sharded: _requirements_/index.md
3. If sharded: Read index + ALL section files
```
**Example 2: Selective Load with Epic Number**
```yaml
# workflow.yaml
input_file_patterns:
epics:
whole: '{output_folder}/*epic*.md'
sharded_single: '{output_folder}/*epic*/epic-{{epic_num}}.md'
```
```xml
<!-- instructions.md step -->
<step n="2" goal="Load Epic Content">
<action>Extract epic number from story key (e.g., "3-2-feature" → epic_num = 3)</action>
<action>Check for sharded epics: {output_folder}/*epic*/index.md</action>
<action if="sharded found">Load ONLY epics/epic-{{epic_num}}.md (selective optimization)</action>
<action if="whole document found">Load full epics.md and extract Epic {{epic_num}}</action>
</step>
```
### Testing Your Sharding Support
1. **Test with whole document**: Verify workflow works with single `document.md`
2. **Test with sharded document**: Create sharded version and verify discovery
3. **Test with both present**: Ensure whole document takes priority
4. **Test selective loading**: Verify only needed sections are loaded (if applicable)
### Complete Reference
**[→ Document Sharding Guide](../../../../docs/document-sharding-guide.md)** - Comprehensive guide with examples
**BMM Examples**:
- Full Load: `src/modules/bmm/workflows/2-plan-workflows/prd/`
- Selective Load: `src/modules/bmm/workflows/4-implementation/epic-tech-context/`
## Web Bundles
Web bundles allow workflows to be deployed as self-contained packages for web environments.