diff --git a/README.md b/README.md index 2d693fa8..8ada2d50 100644 --- a/README.md +++ b/README.md @@ -180,6 +180,17 @@ This initializes the workflow system and helps choose your starting point. Single `bmad/` folder - clean, organized, maintainable. +### πŸ“„ Document Sharding + +Optional efficiency optimization for large projects: + +- **Automatic Support** - All workflows handle whole or sharded documents +- **Selective Loading** - Phase 4 workflows load only needed sections (90%+ token savings) +- **Easy Sharding** - Built-in tool splits documents by headings +- **Smart Discovery** - Workflows auto-detect format + +**[β†’ Document Sharding Guide](./docs/document-sharding-guide.md)** + ## Documentation - **[πŸ“š Documentation Index](./docs/index.md)** - Complete documentation map diff --git a/docs/conversion-report-shard-doc-2025-10-26.md b/docs/conversion-report-shard-doc-2025-10-26.md deleted file mode 100644 index dcf7c382..00000000 --- a/docs/conversion-report-shard-doc-2025-10-26.md +++ /dev/null @@ -1,188 +0,0 @@ -# Legacy Task Conversion Report - -**Generated**: 2025-10-26 -**Converted By**: BMad Builder Agent -**Conversion Type**: Legacy Task β†’ v6 XML Task - ---- - -## Source Information - -- **Original Location**: https://github.com/bmad-code-org/BMAD-METHOD/blob/main/bmad-core/tasks/shard-doc.md -- **Original Format**: Markdown task (v4/legacy format) -- **Original Type**: Document sharding utility task - ---- - -## Target Information - -- **New Location**: `/Users/brianmadison/dev/BMAD-METHOD/src/core/tasks/shard-doc.xml` -- **New Format**: v6 XML task format -- **Task ID**: `bmad/core/tasks/shard-doc` -- **Task Name**: Shard Document - ---- - -## Conversion Summary - -### Components Converted - -βœ… **Task Structure**: Converted from markdown to XML format -βœ… **Execution Flow**: 6 steps properly structured in `` section (simplified to tool-only) -βœ… **Critical Instructions**: Moved to `` section -βœ… **Validation Rules**: Extracted to `` section -βœ… **Halt Conditions**: Extracted to `` section -βœ… **Special Guidelines**: Moved to `` section -βœ… **Output Format**: Documented in `` section -βœ… **Tool Information**: Preserved in `` section - -### Key Features Preserved - -- **Automated Tool**: Uses @kayvan/markdown-tree-parser exclusively -- **Simplified Flow**: Removed all manual steps, tool handles everything -- **Code Block Awareness**: Tool automatically handles ## inside code blocks -- **Content Preservation**: Tool preserves all markdown formatting and special content -- **Heading Adjustment**: Tool automatically reduces heading levels by one -- **Index Generation**: Tool automatically creates index.md -- **Validation Steps**: Verification of tool installation and output -- **Error Handling**: Halt conditions for tool and file system issues - -### v6 Conventions Applied - -- βœ… Proper `` wrapper with id and name attributes -- βœ… `` section with mandatory instructions -- βœ… `` section with numbered `` elements -- βœ… Used `` tags for required actions -- βœ… Used `` tags for instruction lists and context -- βœ… Conditional logic with `if` attributes on actions -- βœ… Optional steps marked with `optional="true"` -- βœ… Supporting sections for validation, halt conditions, output format -- βœ… Consistent with existing v6 tasks (workflow.xml, adv-elicit.xml, index-docs.xml) - ---- - -## Structural Comparison - -### Legacy Format (Markdown) - -``` -# Document Sharding Task -## Primary Method: Automated Approach -## Manual Method (Fallback) -1. Identify target location -2. Parse sections -... -## Critical Guidelines -``` - -### v6 Format (XML) - -```xml - - ... - ... - ... - - - ... - - - ... - ... - -``` - ---- - -## Validation Results - -### XML Structure - -- βœ… Valid XML syntax -- βœ… Properly nested elements -- βœ… All tags closed correctly -- βœ… Attributes properly formatted - -### v6 Compliance - -- βœ… Matches v6 task conventions -- βœ… Follows existing core task patterns -- βœ… Uses standard v6 tag set -- βœ… Proper section organization - -### Content Integrity - -- βœ… All original instructions preserved -- βœ… No functionality lost in conversion -- βœ… Critical warnings maintained -- βœ… Tool information preserved -- βœ… Validation logic intact - -### File System - -- βœ… Saved to correct location: `src/core/tasks/` -- βœ… Proper filename: `shard-doc.xml` -- βœ… Follows core task naming convention - ---- - -## Usage Notes - -### How to Invoke This Task - -From an agent or workflow, reference: - -```xml -{project-root}/bmad/core/tasks/shard-doc.xml -``` - -Or from agent menu: - -```yaml -menu: - - trigger: shard - description: 'Split large document into organized files' - exec: '{project-root}/bmad/core/tasks/shard-doc.xml' -``` - -### Task Capabilities - -1. **Automated Mode**: Uses @kayvan/markdown-tree-parser for fast sharding -2. **Manual Mode**: Step-by-step guided process for controlled sharding -3. **Safety Checks**: Validates code blocks aren't treated as headers -4. **Content Preservation**: Maintains all formatting, code, tables, diagrams -5. **Index Generation**: Creates navigable index.md automatically -6. **Validation**: Verifies completeness and integrity - ---- - -## Post-Conversion Actions - -### Recommended Next Steps - -1. βœ… **Task Created**: File saved to core tasks directory -2. **Test Task**: Invoke from an agent or workflow to verify functionality -3. **Update Documentation**: Reference in core task documentation if needed -4. **Integration**: Add to relevant agent menus if appropriate - -### No Manual Adjustments Required - -The conversion is complete and ready for use. All legacy functionality has been successfully migrated to v6 XML format. - ---- - -## Notes - -- Original legacy file can be archived or left as-is (located on GitHub) -- This task is now a core BMAD task available to all modules -- The task follows v6 conventions and is fully compatible with BMAD-CORE v6 alpha -- **UPDATED 2025-10-26**: Manual fallback steps removed - task now exclusively uses @kayvan/markdown-tree-parser -- Flow simplified from 8 steps to 6 steps (tool installation β†’ execution β†’ verification) -- All manual parsing, file creation, and index generation logic removed (tool handles automatically) - ---- - -**Conversion Status**: βœ… COMPLETE (Updated) -**Ready for Use**: YES -**Manual Adjustments Needed**: NONE -**Approach**: Automated tool only (no manual fallback) diff --git a/docs/document-sharding-guide.md b/docs/document-sharding-guide.md new file mode 100644 index 00000000..5ce83e89 --- /dev/null +++ b/docs/document-sharding-guide.md @@ -0,0 +1,447 @@ +# Document Sharding Guide + +Comprehensive guide to BMad Method's document sharding system for managing large planning and architecture documents. + +## Table of Contents + +- [What is Document Sharding?](#what-is-document-sharding) +- [When to Use Sharding](#when-to-use-sharding) +- [How Sharding Works](#how-sharding-works) +- [Using the Shard-Doc Tool](#using-the-shard-doc-tool) +- [Workflow Support](#workflow-support) +- [Best Practices](#best-practices) +- [Examples](#examples) + +## What is Document Sharding? + +Document sharding splits large markdown files into smaller, organized files based on level 2 headings (`## Heading`). This enables: + +- **Selective Loading** - Workflows load only the sections they need +- **Reduced Token Usage** - Massive efficiency gains for large projects +- **Better Organization** - Logical section-based file structure +- **Maintained Context** - Index file preserves document structure + +### Architecture + +``` +Before Sharding: +docs/ +└── PRD.md (large 50k token file) + +After Sharding: +docs/ +└── prd/ + β”œβ”€β”€ index.md # Table of contents with descriptions + β”œβ”€β”€ overview.md # Section 1 + β”œβ”€β”€ user-requirements.md # Section 2 + β”œβ”€β”€ technical-requirements.md # Section 3 + └── ... # Additional sections +``` + +## When to Use Sharding + +### Ideal Candidates + +**Large Multi-Epic Projects:** + +- Very large complex PRDs +- Architecture documents with multiple system layers +- Epic files with 4+ epics (especially for Phase 4) +- UX design specs covering multiple subsystems + +**Token Thresholds:** + +- **Consider sharding**: Documents > 20k tokens +- **Strongly recommended**: Documents > 40k tokens +- **Critical for efficiency**: Documents > 60k tokens + +### When NOT to Shard + +**Small Projects:** + +- Single epic projects +- Level 0-1 projects (tech-spec only) +- Documents under 10k tokens +- Quick prototypes + +**Frequently Updated Docs:** + +- Active work-in-progress documents +- Documents updated daily +- Documents where whole-file context is essential + +## How Sharding Works + +### Sharding Process + +1. **Tool Execution**: Run `npx @kayvan/markdown-tree-parser source.md destination/` - this is abstracted with the core shard-doc task which is installed as a slash command or manual task rule depending on your tools. +2. **Section Extraction**: Tool splits by level 2 headings +3. **File Creation**: Each section becomes a separate file +4. **Index Generation**: `index.md` created with structure and descriptions + +### Workflow Discovery + +BMad workflows use a **dual discovery system**: + +1. **Try whole document first** - Look for `document-name.md` +2. **Check for sharded version** - Look for `document-name/index.md` +3. **Priority rule** - Whole document takes precedence if both exist + +### Loading Strategies + +**Full Load (Phase 1-3 workflows):** + +``` +If sharded: + - Read index.md + - Read ALL section files + - Treat as single combined document +``` + +**Selective Load (Phase 4 workflows):** + +``` +If sharded epics and working on Epic 3: + - Read epics/index.md + - Load ONLY epics/epic-3.md + - Skip all other epic files + - 90%+ token savings! +``` + +## Using the Shard-Doc Tool + +### CLI Command + +```bash +# Activate bmad-master or analyst agent, then: +/shard-doc +``` + +### Interactive Process + +``` +Agent: Which document would you like to shard? +User: docs/PRD.md + +Agent: Default destination: docs/prd/ + Accept default? [y/n] +User: y + +Agent: Sharding PRD.md... + βœ“ Created 12 section files + βœ“ Generated index.md + βœ“ Complete! +``` + +### What Gets Created + +**index.md structure:** + +```markdown +# PRD - Index + +## Sections + +1. [Overview](./overview.md) - Project vision and objectives +2. [User Requirements](./user-requirements.md) - Feature specifications +3. [Epic 1: Authentication](./epic-1-authentication.md) - User auth system +4. [Epic 2: Dashboard](./epic-2-dashboard.md) - Main dashboard UI + ... +``` + +**Individual section files:** + +- Named from heading text (kebab-case) +- Contains complete section content +- Preserves all markdown formatting +- Can be read independently + +## Workflow Support + +### Universal Support + +**All BMM workflows support both formats:** + +- βœ… Whole documents +- βœ… Sharded documents +- βœ… Automatic detection +- βœ… Transparent to user + +### Workflow-Specific Patterns + +#### Phase 1-3 (Full Load) + +Workflows load entire sharded documents: + +- `product-brief` - Research, brainstorming docs +- `prd` - Product brief, research +- `gdd` - Game brief, research +- `create-ux-design` - PRD, brief, epics +- `tech-spec` - Brief, research +- `architecture` - PRD, epics, UX design +- `solutioning-gate-check` - All planning docs + +#### Phase 4 (Selective Load) + +Workflows load only needed sections: + +**sprint-planning** (Full Load): + +- Needs ALL epics to build complete status + +**epic-tech-context, create-story, story-context, code-review** (Selective): + +``` +Working on Epic 3, Story 2: + βœ“ Load epics/epic-3.md only + βœ— Skip epics/epic-1.md, epic-2.md, epic-4.md, etc. + +Result: 90%+ token reduction for 10-epic projects! +``` + +### Input File Patterns + +Workflows use standardized patterns: + +```yaml +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' +``` + +## Best Practices + +### Sharding Strategy + +**Do:** + +- βœ… Shard after planning phase complete +- βœ… Keep level 2 headings well-organized +- βœ… Use descriptive section names +- βœ… Shard before Phase 4 implementation +- βœ… Keep original file as backup initially + +**Don't:** + +- ❌ Shard work-in-progress documents +- ❌ Shard small documents (<20k tokens) +- ❌ Mix sharded and whole versions +- ❌ Manually edit index.md structure + +### Naming Conventions + +**Good Section Names:** + +```markdown +## Epic 1: User Authentication + +## Technical Requirements + +## System Architecture + +## UX Design Principles +``` + +**Poor Section Names:** + +```markdown +## Section 1 + +## Part A + +## Details + +## More Info +``` + +### File Management + +**When to Re-shard:** + +- Significant structural changes to document +- Adding/removing major sections +- After major refactoring + +**Updating Sharded Docs:** + +1. Edit individual section files directly +2. OR edit original, delete sharded folder, re-shard +3. Don't manually edit index.md + +## Examples + +### Example 1: Large PRD + +**Scenario:** 15-epic project, PRD is 45k tokens + +**Before Sharding:** + +``` +Every workflow loads entire 45k token PRD +Epic-tech-context for Epic 3: 45k tokens +Create-story for Epic 3: 45k tokens +``` + +**After Sharding:** + +```bash +/shard-doc +Source: docs/PRD.md +Destination: docs/prd/ + +Created: + prd/index.md + prd/overview.md (3k tokens) + prd/epic-1-auth.md (3k tokens) + prd/epic-2-dashboard.md (3k tokens) + prd/epic-3-reports.md (3k tokens) + ...15 epic files +``` + +**Result:** + +``` +Epic-tech-context for Epic 3: 3k tokens (93% reduction!) +Create-story for Epic 3: 3k tokens (93% reduction!) +``` + +### Example 2: Sharding Epics File + +**Scenario:** 8 epics with detailed stories, 35k tokens total + +```bash +/shard-doc +Source: docs/bmm-epics.md +Destination: docs/epics/ + +Created: + epics/index.md + epics/epic-1.md + epics/epic-2.md + ... + epics/epic-8.md +``` + +**Efficiency Gain:** + +``` +Working on Epic 5 stories: + Old: Load all 8 epics (35k tokens) + New: Load epic-5.md only (4k tokens) + Savings: 88% reduction +``` + +### Example 3: Architecture Document + +**Scenario:** Multi-layer system architecture, 28k tokens + +```bash +/shard-doc +Source: docs/architecture.md +Destination: docs/architecture/ + +Created: + architecture/index.md + architecture/system-overview.md + architecture/frontend-architecture.md + architecture/backend-services.md + architecture/data-layer.md + architecture/infrastructure.md + architecture/security-architecture.md +``` + +**Benefit:** Code-review workflow can reference specific architectural layers without loading entire architecture doc. + +## Custom Workflow Integration + +### For Workflow Builders + +When creating custom workflows that load large documents: + +**1. Add input_file_patterns to workflow.yaml:** + +```yaml +input_file_patterns: + your_document: + whole: '{output_folder}/*your-doc*.md' + sharded: '{output_folder}/*your-doc*/index.md' +``` + +**2. Add discovery instructions to instructions.md:** + +```markdown +## Document Discovery + +1. Search for whole document: _your-doc_.md +2. Check for sharded version: _your-doc_/index.md +3. If sharded: Read index + ALL sections (or specific sections if selective load) +4. Priority: Whole document first +``` + +**3. Choose loading strategy:** + +- **Full Load**: Read all sections when sharded +- **Selective Load**: Read only relevant sections (requires section identification logic) + +### Pattern Templates + +**Full Load Pattern:** + +```xml +Search for document: {output_folder}/*doc-name*.md +If not found, check for sharded: {output_folder}/*doc-name*/index.md +Read index.md to understand structure +Read ALL section files listed in index +Combine content as single document +``` + +**Selective Load Pattern (with section ID):** + +```xml +Determine section needed (e.g., epic_num = 3) +Check for sharded version: {output_folder}/*doc-name*/index.md +Read ONLY the specific section file needed +Skip all other section files +``` + +## Troubleshooting + +### Common Issues + +**Both whole and sharded exist:** + +- Workflows will use whole document (priority rule) +- Delete or archive the one you don't want + +**Index.md out of sync:** + +- Delete sharded folder +- Re-run shard-doc on original + +**Workflow can't find document:** + +- Check file naming matches patterns (`*prd*.md`, `*epic*.md`, etc.) +- Verify index.md exists in sharded folder +- Check output_folder path in config + +**Sections too granular:** + +- Combine sections in original document +- Use fewer level 2 headings +- Re-shard + +## Related Documentation + +- [shard-doc Tool](../src/core/tools/shard-doc.xml) - Tool implementation +- [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) - Workflow overview +- [Workflow Creation Guide](../src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md) - Custom workflow patterns + +--- + +**Document sharding is optional but powerful** - use it when efficiency matters for large projects! diff --git a/docs/index.md b/docs/index.md index bc43a2c5..30e88a0f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -99,6 +99,10 @@ Instructions for loading agents and running workflows in your development enviro - [Installers & Platforms Reference](./installers-bundlers/installers-modules-platforms-reference.md) - CLI tool and platform support - [Web Bundler Usage](./installers-bundlers/web-bundler-usage.md) - Creating web-compatible bundles +### Optimization & Efficiency + +- **[Document Sharding Guide](./document-sharding-guide.md)** - Split large documents for 90%+ token savings in Phase 4 workflows + --- ## πŸ“Š Documentation Map diff --git a/src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md b/src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md index 5d9436ba..826af3a4 100644 --- a/src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md +++ b/src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md @@ -1020,6 +1020,164 @@ _Generated on {{date}}_ - **Unclosed check tags** - Always close `...` blocks - **Wrong conditional pattern** - Use `` for single items, `` 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 +Search for document using fuzzy pattern: {output_folder}/*prd*.md +If not found, check for sharded version: {output_folder}/*prd*/index.md +Read index.md to understand structure +Read ALL section files listed in index +Combine content as single document +``` + +**Selective Load Strategy** (advanced - for phase 4 type workflows): + +```xml +Determine section needed (e.g., epic_num from story key) +Check for sharded version: {output_folder}/*epics*/index.md +Read ONLY the specific section file: epics/epic-{{epic_num}}.md +Skip all other section files (efficiency optimization) +Load complete document and extract relevant section +``` + +### 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 + + +## 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 + + + Extract epic number from story key (e.g., "3-2-feature" β†’ epic_num = 3) + Check for sharded epics: {output_folder}/*epic*/index.md + Load ONLY epics/epic-{{epic_num}}.md (selective optimization) + Load full epics.md and extract Epic {{epic_num}} + +``` + +### 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. diff --git a/src/modules/bmm/workflows/1-analysis/product-brief/instructions.md b/src/modules/bmm/workflows/1-analysis/product-brief/instructions.md index f44c1423..1b628ffd 100644 --- a/src/modules/bmm/workflows/1-analysis/product-brief/instructions.md +++ b/src/modules/bmm/workflows/1-analysis/product-brief/instructions.md @@ -8,6 +8,24 @@ Generate all documents in {document_output_language} LIVING DOCUMENT: Write to the document continuously as you discover - never wait until the end +## Input Document Discovery + +This workflow may reference: market research, brainstorming documents, user specified other inputs, or brownfield project documentation. + +**Discovery Process** (execute for each referenced document): + +1. **Search for whole document first** - Use fuzzy file matching to find the complete document +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 + - Treat the combined content as if it were a single document +4. **Brownfield projects**: The `document-project` workflow always 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 in naming conventions. + diff --git a/src/modules/bmm/workflows/1-analysis/product-brief/workflow.yaml b/src/modules/bmm/workflows/1-analysis/product-brief/workflow.yaml index 2b5c2b3c..22dcfd58 100644 --- a/src/modules/bmm/workflows/1-analysis/product-brief/workflow.yaml +++ b/src/modules/bmm/workflows/1-analysis/product-brief/workflow.yaml @@ -19,6 +19,20 @@ recommended_inputs: - competitive_analysis: "Competitive analysis (optional)" - initial_ideas: "Initial product ideas or notes (optional)" +# Smart input file references - handles both whole docs and sharded docs +# Priority: Whole document first, then sharded version +input_file_patterns: + research: + whole: "{output_folder}/*research*.md" + sharded: "{output_folder}/*research*/index.md" + + brainstorming: + whole: "{output_folder}/*brainstorm*.md" + sharded: "{output_folder}/*brainstorm*/index.md" + + document_project: + sharded: "{output_folder}/docs/index.md" + # Module path and component files installed_path: "{project-root}/bmad/bmm/workflows/1-analysis/product-brief" template: "{installed_path}/template.md" diff --git a/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/instructions.md b/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/instructions.md index b4a061b9..ebfbc74a 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/instructions.md +++ b/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/instructions.md @@ -12,6 +12,24 @@ DOCUMENT OUTPUT: Professional, specific, actionable UX design decisions WITH RATIONALE. User skill level ({user_skill_level}) affects conversation style ONLY, not document content. +## πŸ“š Input Document Discovery + +This workflow requires: PRD or product brief, and may reference epics/stories, brainstorming documents, or brownfield project documentation. + +**Discovery Process** (execute for each referenced document): + +1. **Search for whole document first** - Use fuzzy file matching to find the complete document +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 + - Treat the combined content as if it were a single document +4. **Brownfield projects**: The `document-project` workflow always 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 in naming conventions. + Check if {output_folder}/bmm-workflow-status.yaml exists diff --git a/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/workflow.yaml b/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/workflow.yaml index d52ec502..fe3a48a9 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/workflow.yaml +++ b/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/workflow.yaml @@ -23,6 +23,28 @@ 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" +# 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" + + product_brief: + whole: "{output_folder}/*brief*.md" + sharded: "{output_folder}/*brief*/index.md" + + epics: + whole: "{output_folder}/*epic*.md" + sharded: "{output_folder}/*epic*/index.md" + + brainstorming: + whole: "{output_folder}/*brainstorm*.md" + sharded: "{output_folder}/*brainstorm*/index.md" + + document_project: + sharded: "{output_folder}/docs/index.md" + # Module path and component files installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/create-ux-design" instructions: "{installed_path}/instructions.md" diff --git a/src/modules/bmm/workflows/2-plan-workflows/gdd/instructions-gdd.md b/src/modules/bmm/workflows/2-plan-workflows/gdd/instructions-gdd.md index bf2e7a1d..d0da8c66 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/gdd/instructions-gdd.md +++ b/src/modules/bmm/workflows/2-plan-workflows/gdd/instructions-gdd.md @@ -14,6 +14,24 @@ DOCUMENT OUTPUT: Concise, clear, actionable game design specs. Use tables/lists over prose. User skill level ({user_skill_level}) affects conversation style ONLY, not document content. +## Input Document Discovery + +This workflow requires: game brief, and may reference market research or brownfield project documentation. + +**Discovery Process** (execute for each referenced document): + +1. **Search for whole document first** - Use fuzzy file matching to find the complete document +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 + - Treat the combined content as if it were a single document +4. **Brownfield projects**: The `document-project` workflow always 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 in naming conventions. + diff --git a/src/modules/bmm/workflows/2-plan-workflows/gdd/workflow.yaml b/src/modules/bmm/workflows/2-plan-workflows/gdd/workflow.yaml index b7732853..9e093634 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/gdd/workflow.yaml +++ b/src/modules/bmm/workflows/2-plan-workflows/gdd/workflow.yaml @@ -30,6 +30,20 @@ recommended_inputs: - narrative_design: "{output_folder}/narrative-design.md" - market_research: "{output_folder}/market-research.md" +# Smart input file references - handles both whole docs and sharded docs +# Priority: Whole document first, then sharded version +input_file_patterns: + game_brief: + whole: "{output_folder}/*game-brief*.md" + sharded: "{output_folder}/*game-brief*/index.md" + + research: + whole: "{output_folder}/*research*.md" + sharded: "{output_folder}/*research*/index.md" + + document_project: + sharded: "{output_folder}/docs/index.md" + standalone: true web_bundle: diff --git a/src/modules/bmm/workflows/2-plan-workflows/prd/instructions.md b/src/modules/bmm/workflows/2-plan-workflows/prd/instructions.md index acda9438..608769ea 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/prd/instructions.md +++ b/src/modules/bmm/workflows/2-plan-workflows/prd/instructions.md @@ -8,6 +8,24 @@ LIVING DOCUMENT: Write to PRD.md continuously as you discover - never wait until the end GUIDING PRINCIPLE: Find and weave the product's magic throughout - what makes it special should inspire every section +## πŸ“š Input Document Discovery + +This workflow requires: product brief, and may reference market research or brownfield project documentation. + +**Discovery Process** (execute for each referenced document): + +1. **Search for whole document first** - Use fuzzy file matching to find the complete document +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 + - Treat the combined content as if it were a single document +4. **Brownfield projects**: The `document-project` workflow always 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 in naming conventions. + diff --git a/src/modules/bmm/workflows/2-plan-workflows/prd/workflow.yaml b/src/modules/bmm/workflows/2-plan-workflows/prd/workflow.yaml index 66b994f7..7d6788d5 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/prd/workflow.yaml +++ b/src/modules/bmm/workflows/2-plan-workflows/prd/workflow.yaml @@ -29,6 +29,20 @@ recommended_inputs: - product_brief: "{output_folder}/product-brief.md" - market_research: "{output_folder}/market-research.md" +# Smart input file references - handles both whole docs and sharded docs +# Priority: Whole document first, then sharded version +input_file_patterns: + product_brief: + whole: "{output_folder}/*brief*.md" + sharded: "{output_folder}/*brief*/index.md" + + research: + whole: "{output_folder}/*research*.md" + sharded: "{output_folder}/*research*/index.md" + + document_project: + sharded: "{output_folder}/docs/index.md" + standalone: true web_bundle: diff --git a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions.md b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions.md index d18da1e8..514de8a1 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions.md +++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions.md @@ -13,6 +13,24 @@ DOCUMENT OUTPUT: Technical, precise, definitive. Specific versions only. User skill level ({user_skill_level}) affects conversation style ONLY, not document content. +## πŸ“š Input Document Discovery + +This workflow may reference: product brief, research documents, or brownfield project documentation. + +**Discovery Process** (execute for each referenced document): + +1. **Search for whole document first** - Use fuzzy file matching to find the complete document +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 + - Treat the combined content as if it were a single document +4. **Brownfield projects**: The `document-project` workflow always 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 in naming conventions. + Check if {output_folder}/bmm-workflow-status.yaml exists diff --git a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml index 89589916..b2090f8e 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml +++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml @@ -36,6 +36,20 @@ recommended_inputs: - bug_report: "Bug description or issue ticket" - feature_request: "Brief feature description" +# Smart input file references - handles both whole docs and sharded docs +# Priority: Whole document first, then sharded version +input_file_patterns: + product_brief: + whole: "{output_folder}/*brief*.md" + sharded: "{output_folder}/*brief*/index.md" + + research: + whole: "{output_folder}/*research*.md" + sharded: "{output_folder}/*research*/index.md" + + document_project: + sharded: "{output_folder}/docs/index.md" + standalone: true web_bundle: diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/instructions.md b/src/modules/bmm/workflows/3-solutioning/architecture/instructions.md index 314de829..e1dae8d6 100644 --- a/src/modules/bmm/workflows/3-solutioning/architecture/instructions.md +++ b/src/modules/bmm/workflows/3-solutioning/architecture/instructions.md @@ -10,6 +10,24 @@ Generate all documents in {document_output_language} This workflow replaces architecture with a conversation-driven approach +## πŸ“š Input Document Discovery + +This workflow requires: PRD and epics/stories, and may reference UX design specifications or brownfield project documentation. + +**Discovery Process** (execute for each referenced document): + +1. **Search for whole document first** - Use fuzzy file matching to find the complete document +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 + - Treat the combined content as if it were a single document +4. **Brownfield projects**: The `document-project` workflow always 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 in naming conventions. + Check if {output_folder}/bmm-workflow-status.yaml exists diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/workflow.yaml b/src/modules/bmm/workflows/3-solutioning/architecture/workflow.yaml index cce09463..7fdda6a2 100644 --- a/src/modules/bmm/workflows/3-solutioning/architecture/workflow.yaml +++ b/src/modules/bmm/workflows/3-solutioning/architecture/workflow.yaml @@ -18,10 +18,23 @@ recommended_inputs: - epics: "Epic definitions with user stories and acceptance criteria" - ux_spec: "UX specification with interface designs and interaction patterns (optional)" -# Input file references (fuzzy matched from output folder) -prd_file: "{output_folder}/*PRD*, PRD.md, or prd/index.md + files" -epics_file: "{output_folder}/bmm-epics.md or epics.md or user-stories.md" -ux_spec_file: "{output_folder}/ux-spec.md or ux-specification.md or user-experience.md" +# 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: "{output_folder}/*epic*/index.md" + + ux_design: + whole: "{output_folder}/*ux*.md" + sharded: "{output_folder}/*ux*/index.md" + + document_project: + sharded: "{output_folder}/docs/index.md" # Module path and component files installed_path: "{project-root}/bmad/bmm/workflows/3-solutioning/architecture" diff --git a/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/instructions.md b/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/instructions.md index 8849abc2..25a6fdbc 100644 --- a/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/instructions.md +++ b/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/instructions.md @@ -4,6 +4,24 @@ You MUST have already loaded and processed: {project-root}/bmad/bmm/workflows/3-solutioning/solutioning-gate-check/workflow.yaml Communicate all findings and analysis in {communication_language} throughout the assessment +## πŸ“š Input Document Discovery + +This workflow validates: PRD, epics/stories, architecture, and may reference UX design, tech specs, or brownfield project documentation. + +**Discovery Process** (execute for each referenced document): + +1. **Search for whole document first** - Use fuzzy file matching to find the complete document +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 + - Treat the combined content as if it were a single document +4. **Brownfield projects**: The `document-project` workflow always 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 in naming conventions. + diff --git a/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/workflow.yaml b/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/workflow.yaml index b1c7031a..5bbb15b0 100644 --- a/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/workflow.yaml +++ b/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/workflow.yaml @@ -32,6 +32,32 @@ recommended_inputs: - epics_stories: "{output_folder}/epic*.md" - ux_artifacts: "{output_folder}/ux*.md" +# 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: "{output_folder}/*epic*/index.md" + + architecture: + whole: "{output_folder}/*architecture*.md" + sharded: "{output_folder}/*architecture*/index.md" + + ux_design: + whole: "{output_folder}/*ux*.md" + sharded: "{output_folder}/*ux*/index.md" + + tech_spec: + whole: "{output_folder}/*tech-spec*.md" + sharded: "{output_folder}/*tech-spec*/index.md" + + document_project: + sharded: "{output_folder}/docs/index.md" + # Validation criteria data validation_criteria: "{installed_path}/validation-criteria.yaml" diff --git a/src/modules/bmm/workflows/4-implementation/code-review/instructions.md b/src/modules/bmm/workflows/4-implementation/code-review/instructions.md index d2a812d0..e277df46 100644 --- a/src/modules/bmm/workflows/4-implementation/code-review/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/code-review/instructions.md @@ -16,6 +16,35 @@ DOCUMENT OUTPUT: Technical review reports. Structured findings with severity levels and action items. User skill level ({user_skill_level}) affects conversation style ONLY, not review content. +## πŸ“š Document Discovery - Selective Epic Loading + +**Strategy**: This workflow needs only ONE specific epic and its stories for review context, not all epics. This provides huge efficiency gains when epics are sharded. + +**Epic Discovery Process (SELECTIVE OPTIMIZATION):** + +1. **Determine which epic** you need (epic_num from story being reviewed - e.g., story "3-2-feature-name" needs Epic 3) +2. **Check for sharded version**: Look for `epics/index.md` +3. **If sharded version found**: + - Read `index.md` to understand structure + - **Load ONLY `epic-{epic_num}.md`** (e.g., `epics/epic-3.md` for Epic 3) + - DO NOT load all epic files - only the one needed! + - This is the key efficiency optimization for large multi-epic projects +4. **If whole document found**: Load the complete `epics.md` file and extract the relevant epic + +**Other Documents (architecture, ux-design) - Full Load:** + +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 structure + - Read ALL section files listed in the index + - Treat combined content as 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. + +**UX-Heavy Projects**: Always check for ux-design documentation as it provides critical context for reviewing UI-focused stories. + diff --git a/src/modules/bmm/workflows/4-implementation/code-review/workflow.yaml b/src/modules/bmm/workflows/4-implementation/code-review/workflow.yaml index 38b5f17e..211f9ac3 100644 --- a/src/modules/bmm/workflows/4-implementation/code-review/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/code-review/workflow.yaml @@ -51,6 +51,26 @@ recommended_inputs: - tech_spec: "Epic technical specification document (auto-discovered)" - story_context_file: "Story context file (.context.xml) (auto-discovered)" +# Smart input file references - handles both whole docs and sharded docs +# Priority: Whole document first, then sharded version +# Strategy: SELECTIVE LOAD - only load the specific epic needed for this story review +input_file_patterns: + architecture: + whole: "{output_folder}/*architecture*.md" + sharded: "{output_folder}/*architecture*/index.md" + + ux_design: + whole: "{output_folder}/*ux*.md" + sharded: "{output_folder}/*ux*/index.md" + + epics: + whole: "{output_folder}/*epic*.md" + sharded_index: "{output_folder}/*epic*/index.md" + sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md" + + document_project: + sharded: "{output_folder}/docs/index.md" + standalone: true web_bundle: false diff --git a/src/modules/bmm/workflows/4-implementation/create-story/instructions.md b/src/modules/bmm/workflows/4-implementation/create-story/instructions.md index a98bb2c0..e5b8182a 100644 --- a/src/modules/bmm/workflows/4-implementation/create-story/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/create-story/instructions.md @@ -7,6 +7,35 @@ This workflow creates or updates the next user story from epics/PRD and architecture context, saving to the configured stories directory and optionally invoking Story Context. DOCUMENT OUTPUT: Concise, technical, actionable story specifications. Use tables/lists for acceptance criteria and tasks. +## πŸ“š Document Discovery - Selective Epic Loading + +**Strategy**: This workflow needs only ONE specific epic and its stories, not all epics. This provides huge efficiency gains when epics are sharded. + +**Epic Discovery Process (SELECTIVE OPTIMIZATION):** + +1. **Determine which epic** you need (epic_num from story context - e.g., story "3-2-feature-name" needs Epic 3) +2. **Check for sharded version**: Look for `epics/index.md` +3. **If sharded version found**: + - Read `index.md` to understand structure + - **Load ONLY `epic-{epic_num}.md`** (e.g., `epics/epic-3.md` for Epic 3) + - DO NOT load all epic files - only the one needed! + - This is the key efficiency optimization for large multi-epic projects +4. **If whole document found**: Load the complete `epics.md` file and extract the relevant epic + +**Other Documents (prd, architecture, ux-design) - Full Load:** + +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 structure + - Read ALL section files listed in the index + - Treat combined content as 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. + +**UX-Heavy Projects**: Always check for ux-design documentation as it provides critical context for UI-focused stories. + diff --git a/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml b/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml index 77f0dded..49d9d67f 100644 --- a/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml @@ -44,6 +44,30 @@ recommended_inputs: - prd: "PRD document" - architecture: "Architecture (optional)" +# Smart input file references - handles both whole docs and sharded docs +# Priority: Whole document first, then sharded version +# Strategy: SELECTIVE LOAD - only load the specific epic needed for this story +input_file_patterns: + prd: + whole: "{output_folder}/*prd*.md" + sharded: "{output_folder}/*prd*/index.md" + + architecture: + whole: "{output_folder}/*architecture*.md" + sharded: "{output_folder}/*architecture*/index.md" + + ux_design: + whole: "{output_folder}/*ux*.md" + sharded: "{output_folder}/*ux*/index.md" + + epics: + whole: "{output_folder}/*epic*.md" + sharded_index: "{output_folder}/*epic*/index.md" + sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md" + + document_project: + sharded: "{output_folder}/docs/index.md" + standalone: true web_bundle: false diff --git a/src/modules/bmm/workflows/4-implementation/epic-tech-context/instructions.md b/src/modules/bmm/workflows/4-implementation/epic-tech-context/instructions.md index d0b70271..57a7c280 100644 --- a/src/modules/bmm/workflows/4-implementation/epic-tech-context/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/epic-tech-context/instructions.md @@ -7,6 +7,35 @@ This workflow generates a comprehensive Technical Specification from PRD and Architecture, including detailed design, NFRs, acceptance criteria, and traceability mapping. If required inputs cannot be auto-discovered HALT with a clear message listing missing documents, allow user to provide them to proceed. +## πŸ“š Document Discovery - Selective Epic Loading + +**Strategy**: This workflow needs only ONE specific epic and its stories, not all epics. This provides huge efficiency gains when epics are sharded. + +**Epic Discovery Process (SELECTIVE OPTIMIZATION):** + +1. **Determine which epic** you need (epic_num from workflow context or user input) +2. **Check for sharded version**: Look for `epics/index.md` +3. **If sharded version found**: + - Read `index.md` to understand structure + - **Load ONLY `epic-{epic_num}.md`** (e.g., `epics/epic-3.md` for Epic 3) + - DO NOT load all epic files - only the one needed! + - This is the key efficiency optimization for large multi-epic projects +4. **If whole document found**: Load the complete `epics.md` file and extract the relevant epic + +**Other Documents (prd, gdd, architecture, ux-design) - Full Load:** + +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 structure + - Read ALL section files listed in the index + - Treat combined content as 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. + +**UX-Heavy Projects**: Always check for ux-design documentation as it provides critical context for UI-focused epics and stories. + Identify PRD and Architecture documents from recommended_inputs. Attempt to auto-discover at default paths. diff --git a/src/modules/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml b/src/modules/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml index 7c854845..ae6f3301 100644 --- a/src/modules/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml @@ -9,17 +9,43 @@ user_name: "{config_source}:user_name" communication_language: "{config_source}:communication_language" date: system-generated -# Inputs expected ( check output_folder or ask user if missing) +# Inputs expected (check output_folder or ask user if missing) recommended_inputs: - prd - gdd - - spec - architecture - - ux_spec - - ux-design - - if there is an index.md then read the index.md to find other related docs that could be relevant + - ux_design + - epics (only the specific epic needed for this tech spec) - prior epic tech-specs for model, style and consistency reference +# Smart input file references - handles both whole docs and sharded docs +# Priority: Whole document first, then sharded version +# Strategy: SELECTIVE LOAD - only load the specific epic needed (epic_num from context) +input_file_patterns: + prd: + whole: "{output_folder}/*prd*.md" + sharded: "{output_folder}/*prd*/index.md" + + gdd: + whole: "{output_folder}/*gdd*.md" + sharded: "{output_folder}/*gdd*/index.md" + + architecture: + whole: "{output_folder}/*architecture*.md" + sharded: "{output_folder}/*architecture*/index.md" + + ux_design: + whole: "{output_folder}/*ux*.md" + sharded: "{output_folder}/*ux*/index.md" + + epics: + whole: "{output_folder}/*epic*.md" + sharded_index: "{output_folder}/*epic*/index.md" + sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md" + + document_project: + sharded: "{output_folder}/docs/index.md" + # Workflow components installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/epic-tech-context" template: "{installed_path}/template.md" diff --git a/src/modules/bmm/workflows/4-implementation/retrospective/instructions.md b/src/modules/bmm/workflows/4-implementation/retrospective/instructions.md index b8907d3b..a8de8e34 100644 --- a/src/modules/bmm/workflows/4-implementation/retrospective/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/retrospective/instructions.md @@ -6,8 +6,8 @@ Generate all documents in {document_output_language} +DOCUMENT OUTPUT: Retrospective analysis. Concise insights, lessons learned, action items. User skill level ({user_skill_level}) affects conversation style ONLY, not retrospective content. -DOCUMENT OUTPUT: Retrospective analysis. Concise insights, lessons learned, action items. User skill level ({user_skill_level}) affects conversation style ONLY, not retrospective content. FACILITATION NOTES: - Scrum Master facilitates this retrospective @@ -16,22 +16,107 @@ FACILITATION NOTES: - Everyone contributes with specific examples preferred - Action items must be achievable with clear ownership - Two-part format: (1) Epic Review + (2) Next Epic Preparation + +PARTY MODE PROTOCOL: + +- ALL agent dialogue MUST use format: "Name (Role): dialogue" +- Example: Bob (Scrum Master): "Let's begin..." +- Example: {user_name} (Project Lead): [User responds] +- Create natural back-and-forth with user actively participating +- Show disagreements, diverse perspectives, authentic team dynamics +## πŸ“š Document Discovery - Selective Epic Loading + +**Strategy**: This workflow needs the completed epic, previous retrospective, and potentially architecture/PRD for context. + +**Epic Discovery (SELECTIVE LOAD):** + +1. Determine completed epic number (from sprint-status or user) +2. If sharded: Load ONLY `epic-{epic_num}.md` +3. If whole: Load complete epics file and extract relevant epic + +**Retrospective History:** + +1. Load previous epic's retrospective to check if lessons were applied +2. Pattern: `retrospectives/epic-{prev_num}-retro-*.md` + +**Supporting Documents (Full Load if needed):** + +1. Architecture: Check for whole document first, then sharded index + all sections +2. PRD: Same pattern as architecture +3. These provide additional context for understanding epic execution + +**Priority**: Whole document first, then sharded version. + - -Help the user identify which epic was just completed through natural conversation -Attempt to auto-detect by checking {output_folder}/stories/ for the highest numbered completed story and extracting the epic number -If auto-detection succeeds, confirm with user: "It looks like Epic {{epic_number}} was just completed - is that correct?" -If auto-detection fails or user indicates different epic, ask them to share which epic they just completed + -Verify epic completion status: +Explain to {user_name} the epic discovery process using natural dialogue -Load the FULL file: {output_folder}/sprint-status.yaml + +Bob (Scrum Master): "Welcome to the retrospective, {user_name}. Let me help you identify which epic we just completed. I'll check sprint-status first, but you're the ultimate authority on what we're reviewing today." + + +PRIORITY 1: Check sprint-status.yaml first + +Load the FULL file: {sprint_status_file} Read ALL development_status entries +Find the highest epic number with at least one story marked "done" +Extract epic number from keys like "epic-X-retrospective" or story keys like "X-Y-story-name" +Set {{detected_epic}} = highest epic number found with completed stories -Find all stories for epic {{epic_number}}: + + Present finding to user with context + + +Bob (Scrum Master): "Based on sprint-status.yaml, it looks like Epic {{detected_epic}} was recently completed. Is that the epic you want to review today, {user_name}?" + + +WAIT for {user_name} to confirm or correct + + + Set {{epic_number}} = {{detected_epic}} + + + + Set {{epic_number}} = user-provided number + +Bob (Scrum Master): "Got it, we're reviewing Epic {{epic_number}}. Let me gather that information." + + + + + + PRIORITY 2: Ask user directly + + +Bob (Scrum Master): "I'm having trouble detecting the completed epic from sprint-status.yaml. {user_name}, which epic number did you just complete?" + + +WAIT for {user_name} to provide epic number +Set {{epic_number}} = user-provided number + + + + PRIORITY 3: Fallback to stories folder + +Scan {story_directory} for highest numbered story files +Extract epic numbers from story filenames (pattern: epic-X-Y-story-name.md) +Set {{detected_epic}} = highest epic number found + + +Bob (Scrum Master): "I found stories for Epic {{detected_epic}} in the stories folder. Is that the epic we're reviewing, {user_name}?" + + +WAIT for {user_name} to confirm or correct +Set {{epic_number}} = confirmed number + + +Once {{epic_number}} is determined, verify epic completion status + +Find all stories for epic {{epic_number}} in sprint-status.yaml: - Look for keys starting with "{{epic_number}}-" (e.g., "1-1-", "1-2-", etc.) - Exclude epic key itself ("epic-{{epic_number}}") @@ -44,7 +129,10 @@ FACILITATION NOTES: Determine if complete: true if all stories are done, false otherwise - ⚠️ Epic {{epic_number}} is not yet complete for retrospective + +Alice (Product Owner): "Wait, Bob - I'm seeing that Epic {{epic_number}} isn't actually complete yet." + +Bob (Scrum Master): "Let me check... you're right, Alice." **Epic Status:** @@ -55,123 +143,368 @@ FACILITATION NOTES: **Pending Stories:** {{pending_story_list}} +Bob (Scrum Master): "{user_name}, we typically run retrospectives after all stories are done. What would you like to do?" + **Options:** -1. Complete remaining stories before running retrospective -2. Continue with partial retrospective (not recommended) +1. Complete remaining stories before running retrospective (recommended) +2. Continue with partial retrospective (not ideal, but possible) 3. Run sprint-planning to refresh story tracking -Epic is incomplete. Continue anyway? (yes/no) +Continue with incomplete epic? (yes/no) + +Bob (Scrum Master): "Smart call, {user_name}. Let's finish those stories first and then have a proper retrospective." + HALT Set {{partial_retrospective}} = true - + +Charlie (Senior Dev): "Just so everyone knows, this partial retro might miss some important lessons from those pending stories." - - βœ… Epic {{epic_number}} is complete - all {{done_stories}} stories done! - -Ready to proceed with retrospective. +Bob (Scrum Master): "Good point, Charlie. {user_name}, we'll document what we can now, but we may want to revisit after everything's done." -Load the completed epic from: {output_folder}/prd/epic-{{epic_number}}.md -Extract epic details: + + +Alice (Product Owner): "Excellent! All {{done_stories}} stories are marked done." -- Epic title and goals -- Success criteria -- Planned stories and story points -- Estimated sprint duration -- Business objectives - +Bob (Scrum Master): "Perfect. Epic {{epic_number}} is complete and ready for retrospective, {user_name}." + + -Find all stories for this epic in {output_folder}/stories/ -For each story, extract: - Story number and title - Completion status - Story points (if tracked) - Actual completion date - Dev Agent Record notes - TEA Results and testing outcomes - PO Notes and acceptance - Blockers encountered and resolution - Technical debt incurred - - -Calculate epic metrics: - Completed stories vs. total planned - Actual story points delivered vs. planned - Actual sprints taken vs. estimated - Velocity (points per sprint) - Blocker count - Technical debt items logged - - -Review epic goals and compare actual outcomes vs. planned -Note any scope changes or descoped items -Document key architectural decisions made during epic -Identify technical debt incurred and why - -Identify the next epic in sequence -Load next epic from: {output_folder}/prd/epic-{{next_epic_number}}.md + - -Analyze next epic for: + +Bob (Scrum Master): "Before we start the team discussion, let me review all the story records to surface key themes. This'll help us have a richer conversation." + +Charlie (Senior Dev): "Good idea - those dev notes always have gold in them." + + +For each story in epic {{epic_number}}, read the complete story file from {story_directory}/{{epic_number}}-{{story_num}}-\*.md + +Extract and analyze from each story: + +**Dev Notes and Struggles:** + +- Look for sections like "## Dev Notes", "## Implementation Notes", "## Challenges", "## Development Log" +- Identify where developers struggled or made mistakes +- Note unexpected complexity or gotchas discovered +- Record technical decisions that didn't work out as planned +- Track where estimates were way off (too high or too low) + +**Review Feedback Patterns:** + +- Look for "## Review", "## Code Review", "## SM Review", "## Scrum Master Review" sections +- Identify recurring feedback themes across stories +- Note which types of issues came up repeatedly +- Track quality concerns or architectural misalignments +- Document praise or exemplary work called out in reviews + +**Lessons Learned:** + +- Look for "## Lessons Learned", "## Retrospective Notes", "## Takeaways" sections within stories +- Extract explicit lessons documented during development +- Identify "aha moments" or breakthroughs +- Note what would be done differently +- Track successful experiments or approaches + +**Technical Debt Incurred:** + +- Look for "## Technical Debt", "## TODO", "## Known Issues", "## Future Work" sections +- Document shortcuts taken and why +- Track debt items that affect next epic +- Note severity and priority of debt items + +**Testing and Quality Insights:** + +- Look for "## Testing", "## QA Notes", "## Test Results" sections +- Note testing challenges or surprises +- Track bug patterns or regression issues +- Document test coverage gaps + +Synthesize patterns across all stories: + +**Common Struggles:** + +- Identify issues that appeared in 2+ stories (e.g., "3 out of 5 stories had API authentication issues") +- Note areas where team consistently struggled +- Track where complexity was underestimated + +**Recurring Review Feedback:** + +- Identify feedback themes (e.g., "Error handling was flagged in every review") +- Note quality patterns (positive and negative) +- Track areas where team improved over the course of epic + +**Breakthrough Moments:** + +- Document key discoveries (e.g., "Story 3 discovered the caching pattern we used for rest of epic") +- Note when team velocity improved dramatically +- Track innovative solutions worth repeating + +**Velocity Patterns:** + +- Calculate average completion time per story +- Note velocity trends (e.g., "First 2 stories took 3x longer than estimated") +- Identify which types of stories went faster/slower + +**Team Collaboration Highlights:** + +- Note moments of excellent collaboration mentioned in stories +- Track where pair programming or mob programming was effective +- Document effective problem-solving sessions + +Store this synthesis - these patterns will drive the retrospective discussion + + +Bob (Scrum Master): "Okay, I've reviewed all {{total_stories}} story records. I found some really interesting patterns we should discuss." + +Dana (QA Engineer): "I'm curious what you found, Bob. I noticed some things in my testing too." + +Bob (Scrum Master): "We'll get to all of it. But first, let me load the previous epic's retro to see if we learned from last time." + + + + + + +Calculate previous epic number: {{prev_epic_num}} = {{epic_number}} - 1 + + + Search for previous retrospective using pattern: {retrospectives_folder}/epic-{{prev_epic_num}}-retro-*.md + + + +Bob (Scrum Master): "I found our retrospective from Epic {{prev_epic_num}}. Let me see what we committed to back then..." + + + Read the complete previous retrospective file + + Extract key elements: + - **Action items committed**: What did the team agree to improve? + - **Lessons learned**: What insights were captured? + - **Process improvements**: What changes were agreed upon? + - **Technical debt flagged**: What debt was documented? + - **Team agreements**: What commitments were made? + - **Preparation tasks**: What was needed for this epic? + + Cross-reference with current epic execution: + + **Action Item Follow-Through:** + - For each action item from Epic {{prev_epic_num}} retro, check if it was completed + - Look for evidence in current epic's story records + - Mark each action item: βœ… Completed, ⏳ In Progress, ❌ Not Addressed + + **Lessons Applied:** + - For each lesson from Epic {{prev_epic_num}}, check if team applied it in Epic {{epic_number}} + - Look for evidence in dev notes, review feedback, or outcomes + - Document successes and missed opportunities + + **Process Improvements Effectiveness:** + - For each process change agreed to in Epic {{prev_epic_num}}, assess if it helped + - Did the change improve velocity, quality, or team satisfaction? + - Should we keep, modify, or abandon the change? + + **Technical Debt Status:** + - For each debt item from Epic {{prev_epic_num}}, check if it was addressed + - Did unaddressed debt cause problems in Epic {{epic_number}}? + - Did the debt grow or shrink? + + Prepare "continuity insights" for the retrospective discussion + + Identify wins where previous lessons were applied successfully: + - Document specific examples of applied learnings + - Note positive impact on Epic {{epic_number}} outcomes + - Celebrate team growth and improvement + + Identify missed opportunities where previous lessons were ignored: + - Document where team repeated previous mistakes + - Note impact of not applying lessons (without blame) + - Explore barriers that prevented application + + + +Bob (Scrum Master): "Interesting... in Epic {{prev_epic_num}}'s retro, we committed to {{action_count}} action items." + +Alice (Product Owner): "How'd we do on those, Bob?" + +Bob (Scrum Master): "We completed {{completed_count}}, made progress on {{in_progress_count}}, but didn't address {{not_addressed_count}}." + +Charlie (Senior Dev): _looking concerned_ "Which ones didn't we address?" + +Bob (Scrum Master): "We'll discuss that in the retro. Some of them might explain challenges we had this epic." + +Elena (Junior Dev): "That's... actually pretty insightful." + +Bob (Scrum Master): "That's why we track this stuff. Pattern recognition helps us improve." + + + + + + +Bob (Scrum Master): "I don't see a retrospective for Epic {{prev_epic_num}}. Either we skipped it, or this is your first retro." + +Alice (Product Owner): "Probably our first one. Good time to start the habit!" + +Set {{first_retrospective}} = true + + + + + +Bob (Scrum Master): "This is Epic 1, so naturally there's no previous retro to reference. We're starting fresh!" + +Charlie (Senior Dev): "First epic, first retro. Let's make it count." + +Set {{first_retrospective}} = true + + + + + + +Calculate next epic number: {{next_epic_num}} = {{epic_number}} + 1 + + +Bob (Scrum Master): "Before we dive into the discussion, let me take a quick look at Epic {{next_epic_num}} to understand what's coming." + +Alice (Product Owner): "Good thinking - helps us connect what we learned to what we're about to do." + + +Attempt to load next epic using selective loading strategy: + +**Try sharded first (more specific):** +Check if file exists: {output*folder}/\_epic*/epic-{{next_epic_num}}.md + + + Load {output_folder}/*epic*/epic-{{next_epic_num}}.md + Set {{next_epic_source}} = "sharded" + + +**Fallback to whole document:** + +Check if file exists: {output*folder}/\_epic*.md + + + Load entire epics document + Extract Epic {{next_epic_num}} section + Set {{next_epic_source}} = "whole" + + + + + Analyze next epic for: - Epic title and objectives - - Planned stories and complexity - - Dependencies on completed epic work + - Planned stories and complexity estimates + - Dependencies on Epic {{epic_number}} work - New technical requirements or capabilities needed - Potential risks or unknowns - + - Business goals and success criteria -Identify dependencies on completed work: +Identify dependencies on completed work: -- What components from Epic {{completed_number}} does Epic {{next_number}} rely on? +- What components from Epic {{epic_number}} does Epic {{next_epic_num}} rely on? - Are all prerequisites complete and stable? - Any incomplete work that creates blocking dependencies? - -Note potential gaps or preparation needed: +Note potential gaps or preparation needed: - Technical setup required (infrastructure, tools, libraries) - Knowledge gaps to fill (research, training, spikes) - Refactoring needed before starting next epic - Documentation or specifications to create - -Check for technical prerequisites: +Check for technical prerequisites: - APIs or integrations that must be ready - Data migrations or schema changes needed - Testing infrastructure requirements - Deployment or environment setup - + + +Bob (Scrum Master): "Alright, I've reviewed Epic {{next_epic_num}}: '{{next_epic_title}}'" + +Alice (Product Owner): "What are we looking at?" + +Bob (Scrum Master): "{{next_epic_num}} stories planned, building on the {{dependency_description}} from Epic {{epic_number}}." + +Charlie (Senior Dev): "Dependencies concern me. Did we finish everything we need for that?" + +Bob (Scrum Master): "Good question - that's exactly what we need to explore in this retro." + + +Set {{next_epic_exists}} = true + + + + +Bob (Scrum Master): "Hmm, I don't see Epic {{next_epic_num}} defined yet." + +Alice (Product Owner): "We might be at the end of the roadmap, or we haven't planned that far ahead yet." + +Bob (Scrum Master): "No problem. We'll still do a thorough retro on Epic {{epic_number}}. The lessons will be valuable whenever we plan the next work." + + +Set {{next_epic_exists}} = false + - -Scrum Master opens the retrospective with context -Present formatted retrospective header: + -``` -πŸ”„ TEAM RETROSPECTIVE - Epic {{epic_number}}: {{epic_title}} +Load agent configurations from {agent_manifest} +Identify which agents participated in Epic {{epic_number}} based on story records +Ensure key roles present: Product Owner, Scrum Master (facilitating), Devs, Testing/QA, Architect -Scrum Master facilitating + +Bob (Scrum Master): "Alright team, everyone's here. Let me set the stage for our retrospective." +═══════════════════════════════════════════════════════════ +πŸ”„ TEAM RETROSPECTIVE - Epic {{epic_number}}: {{epic_title}} ═══════════════════════════════════════════════════════════ -EPIC {{epic_number}} SUMMARY: +Bob (Scrum Master): "Here's what we accomplished together." + +**EPIC {{epic_number}} SUMMARY:** Delivery Metrics: + - Completed: {{completed_stories}}/{{total_stories}} stories ({{completion_percentage}}%) -- Velocity: {{actual_points}} story points (planned: {{planned_points}}) -- Duration: {{actual_sprints}} sprints (planned: {{planned_sprints}}) +- Velocity: {{actual_points}} story points{{#if planned_points}} (planned: {{planned_points}}){{/if}} +- Duration: {{actual_sprints}} sprints{{#if planned_sprints}} (planned: {{planned_sprints}}){{/if}} - Average velocity: {{points_per_sprint}} points/sprint Quality and Technical: + - Blockers encountered: {{blocker_count}} - Technical debt items: {{debt_count}} - Test coverage: {{coverage_info}} - Production incidents: {{incident_count}} Business Outcomes: + - Goals achieved: {{goals_met}}/{{total_goals}} - Success criteria: {{criteria_status}} - Stakeholder feedback: {{feedback_summary}} -═══════════════════════════════════════════════════════════ +Alice (Product Owner): "Those numbers tell a good story. {{completion_percentage}}% completion is {{#if completion_percentage >= 90}}excellent{{else}}something we should discuss{{/if}}." -NEXT EPIC PREVIEW: Epic {{next_number}}: {{next_epic_title}} +Charlie (Senior Dev): "I'm more interested in that technical debt number - {{debt_count}} items is {{#if debt_count > 10}}concerning{{else}}manageable{{/if}}." + +Dana (QA Engineer): "{{incident_count}} production incidents - {{#if incident_count == 0}}clean epic!{{else}}we should talk about those{{/if}}." + +{{#if next_epic_exists}} +═══════════════════════════════════════════════════════════ +**NEXT EPIC PREVIEW:** Epic {{next_epic_num}}: {{next_epic_title}} +═══════════════════════════════════════════════════════════ Dependencies on Epic {{epic_number}}: {{list_dependencies}} @@ -182,298 +515,946 @@ Preparation Needed: Technical Prerequisites: {{list_technical_prereqs}} +Bob (Scrum Master): "And here's what's coming next. Epic {{next_epic_num}} builds on what we just finished." + +Elena (Junior Dev): "Wow, that's a lot of dependencies on our work." + +Charlie (Senior Dev): "Which means we better make sure Epic {{epic_number}} is actually solid before moving on." +{{/if}} + ═══════════════════════════════════════════════════════════ -Team assembled for reflection: -{{list_agents_based_on_story_records}} +Bob (Scrum Master): "Team assembled for this retrospective:" + +{{list_participating_agents}} + +Bob (Scrum Master): "{user_name}, you're joining us as Project Lead. Your perspective is crucial here." + +{user_name} (Project Lead): [Participating in the retrospective] + +Bob (Scrum Master): "Our focus today:" -Focus Areas: 1. Learning from Epic {{epic_number}} execution -2. Preparing for Epic {{next_number}} success -``` + {{#if next_epic_exists}}2. Preparing for Epic {{next_epic_num}} success{{/if}} - +Bob (Scrum Master): "Ground rules: psychological safety first. No blame, no judgment. We focus on systems and processes, not individuals. Everyone's voice matters. Specific examples are better than generalizations." + +Alice (Product Owner): "And everything shared here stays in this room - unless we decide together to escalate something." + +Bob (Scrum Master): "Exactly. {user_name}, any questions before we dive in?" + + +WAIT for {user_name} to respond or indicate readiness -Load agent configurations from {agent-manifest} -Ensure key roles present from the {agent_manifest}: Product Owner, Scrum Master (facilitating the retro), Devs, Testing or QA, Architect, Analyst - -Scrum Master facilitates Part 1: Reviewing the completed epic through natural, psychologically safe discussion -Create space for each agent to share their perspective in their unique voice and communication style, grounded in actual story data and outcomes -Maintain psychological safety throughout - focus on learning and systems, not blame or individual performance + -Guide the retrospective conversation to naturally surface key themes across three dimensions: + +Bob (Scrum Master): "Let's start with the good stuff. What went well in Epic {{epic_number}}?" -**1. Successes and Strengths:** -Facilitate discussion that helps agents share what worked well during the epic - encourage specific examples from completed stories, effective practices, velocity achievements, collaboration wins, and smart technical decisions -Draw out concrete examples: "Can you share a specific story where that approach worked well?" +Bob (Scrum Master): _pauses, creating space_ -**2. Challenges and Growth Areas:** -Create safe space for agents to explore challenges encountered - guide them to discuss blockers, process friction, technical debt decisions, and coordination issues with curiosity rather than judgment -Probe for root causes: "What made that challenging? What pattern do we see here?" -Keep focus on systems and processes, not individuals +Alice (Product Owner): "I'll start. The user authentication flow we delivered exceeded my expectations. The UX is smooth, and early user feedback has been really positive." -**3. Insights and Learning:** -Help the team articulate what they learned from this epic - facilitate discovery of patterns to repeat or avoid, skills gained, and process improvements worth trying -Connect insights to future application: "How might this insight help us in future epics?" +Charlie (Senior Dev): "I'll add to that - the caching strategy we implemented in Story {{breakthrough_story_num}} was a game-changer. We cut API calls by 60% and it set the pattern for the rest of the epic." -For each agent participating (loaded from {agent_manifest}): +Dana (QA Engineer): "From my side, testing went smoother than usual. The dev team's documentation was way better this epic - actually usable test plans!" -- Let them speak naturally in their role's voice and communication style -- Encourage grounding in specific story records, metrics, and real outcomes -- Allow themes to emerge organically rather than forcing a rigid structure -- Follow interesting threads with adaptive questions -- Balance celebration with honest assessment +Elena (Junior Dev): _smiling_ "That's because Charlie made me document everything after Story 1's code review!" + +Charlie (Senior Dev): _laughing_ "Tough love pays off." + + +Bob (Scrum Master) naturally turns to {user_name} to engage them in the discussion + + +Bob (Scrum Master): "{user_name}, what stood out to you as going well in this epic?" + + +WAIT for {user_name} to respond - this is a KEY USER INTERACTION moment + +After {user_name} responds, have 1-2 team members react to or build on what {user_name} shared + + +Alice (Product Owner): [Responds naturally to what {user_name} said, either agreeing, adding context, or offering a different perspective] + +Charlie (Senior Dev): [Builds on the discussion, perhaps adding technical details or connecting to specific stories] + + +Continue facilitating natural dialogue, periodically bringing {user_name} back into the conversation + +After covering successes, guide the transition to challenges with care + + +Bob (Scrum Master): "Okay, we've celebrated some real wins. Now let's talk about challenges - where did we struggle? What slowed us down?" + +Bob (Scrum Master): _creates safe space with tone and pacing_ + +Elena (Junior Dev): _hesitates_ "Well... I really struggled with the database migrations in Story {{difficult_story_num}}. The documentation wasn't clear, and I had to redo it three times. Lost almost a full sprint on that story alone." + +Charlie (Senior Dev): _defensive_ "Hold on - I wrote those migration docs, and they were perfectly clear. The issue was that the requirements kept changing mid-story!" + +Alice (Product Owner): _frustrated_ "That's not fair, Charlie. We only clarified requirements once, and that was because the technical team didn't ask the right questions during planning!" + +Charlie (Senior Dev): _heat rising_ "We asked plenty of questions! You said the schema was finalized, then two days into development you wanted to add three new fields!" + +Bob (Scrum Master): _intervening calmly_ "Let's take a breath here. This is exactly the kind of thing we need to unpack." + +Bob (Scrum Master): "Elena, you spent almost a full sprint on Story {{difficult_story_num}}. Charlie, you're saying requirements changed. Alice, you feel the right questions weren't asked up front." + +Bob (Scrum Master): "{user_name}, you have visibility across the whole project. What's your take on this situation?" + + +WAIT for {user_name} to respond and help facilitate the conflict resolution + +Use {user_name}'s response to guide the discussion toward systemic understanding rather than blame + + +Bob (Scrum Master): [Synthesizes {user_name}'s input with what the team shared] "So it sounds like the core issue was {{root_cause_based_on_discussion}}, not any individual person's fault." + +Elena (Junior Dev): "That makes sense. If we'd had {{preventive_measure}}, I probably could have avoided those redos." + +Charlie (Senior Dev): _softening_ "Yeah, and I could have been clearer about assumptions in the docs. Sorry for getting defensive, Alice." + +Alice (Product Owner): "I appreciate that. I could've been more proactive about flagging the schema additions earlier, too." + +Bob (Scrum Master): "This is good. We're identifying systemic improvements, not assigning blame." + + +Continue the discussion, weaving in patterns discovered from the deep story analysis (Step 2) + + +Bob (Scrum Master): "Speaking of patterns, I noticed something when reviewing all the story records..." + +Bob (Scrum Master): "{{pattern_1_description}} - this showed up in {{pattern_1_count}} out of {{total_stories}} stories." + +Dana (QA Engineer): "Oh wow, I didn't realize it was that widespread." + +Bob (Scrum Master): "Yeah. And there's more - {{pattern_2_description}} came up in almost every code review." + +Charlie (Senior Dev): "That's... actually embarrassing. We should've caught that pattern earlier." + +Bob (Scrum Master): "No shame, Charlie. Now we know, and we can improve. {user_name}, did you notice these patterns during the epic?" + + +WAIT for {user_name} to share their observations + +Continue the retrospective discussion, creating moments where: + +- Team members ask {user_name} questions directly +- {user_name}'s input shifts the discussion direction +- Disagreements arise naturally and get resolved +- Quieter team members are invited to contribute +- Specific stories are referenced with real examples +- Emotions are authentic (frustration, pride, concern, hope) + + + +Bob (Scrum Master): "Before we move on, I want to circle back to Epic {{prev_epic_num}}'s retrospective." + +Bob (Scrum Master): "We made some commitments in that retro. Let's see how we did." + +Bob (Scrum Master): "Action item 1: {{prev_action_1}}. Status: {{prev_action_1_status}}" + +Alice (Product Owner): {{#if prev_action_1_status == "completed"}}"We nailed that one!"{{else}}"We... didn't do that one."{{/if}} + +Charlie (Senior Dev): {{#if prev_action_1_status == "completed"}}"And it helped! I noticed {{evidence_of_impact}}"{{else}}"Yeah, and I think that's why we had {{consequence_of_not_doing_it}} this epic."{{/if}} + +Bob (Scrum Master): "Action item 2: {{prev_action_2}}. Status: {{prev_action_2_status}}" + +Dana (QA Engineer): {{#if prev_action_2_status == "completed"}}"This one made testing so much easier this time."{{else}}"If we'd done this, I think testing would've gone faster."{{/if}} + +Bob (Scrum Master): "{user_name}, looking at what we committed to last time and what we actually did - what's your reaction?" + + +WAIT for {user_name} to respond + +Use the previous retro follow-through as a learning moment about commitment and accountability + + + +Bob (Scrum Master): "Alright, we've covered a lot of ground. Let me summarize what I'm hearing..." + +Bob (Scrum Master): "**Successes:**" +{{list_success_themes}} + +Bob (Scrum Master): "**Challenges:**" +{{list_challenge_themes}} + +Bob (Scrum Master): "**Key Insights:**" +{{list_insight_themes}} + +Bob (Scrum Master): "Does that capture it? Anyone have something important we missed?" + + +Allow team members to add any final thoughts on the epic review +Ensure {user_name} has opportunity to add their perspective -As facilitator, actively synthesize common themes and patterns as the discussion unfolds -Notice when multiple agents mention similar issues or successes - call these out to deepen the team's shared understanding -Ensure every voice is heard, inviting quieter agents to contribute - -Scrum Master facilitates Part 2: Preparing for the next epic through forward-looking exploration -Shift the team's focus from reflection to readiness - guide each agent to explore preparation needs from their domain perspective + -Facilitate discovery across critical preparation dimensions: + + +Bob (Scrum Master): "Normally we'd discuss preparing for the next epic, but since Epic {{next_epic_num}} isn't defined yet, let's skip to action items." + + Skip to Step 8 + -**Dependencies and Continuity:** -Guide agents to explore connections between the completed epic and the upcoming one - help them identify what components, decisions, or work from Epic {{completed_number}} the next epic relies upon -Probe for gaps: "What needs to be in place before we can start Epic {{next_number}}?" -Surface hidden dependencies: "Are there integration points we need to verify?" + +Bob (Scrum Master): "Now let's shift gears. Epic {{next_epic_num}} is coming up: '{{next_epic_title}}'" -**Readiness and Setup:** -Facilitate discussion about what preparation work is needed before the next epic can begin successfully - technical setup, knowledge development, refactoring, documentation, or infrastructure -Draw out specific needs: "What do you need to feel ready to start Epic {{next_number}}?" -Identify knowledge gaps: "What do we need to learn or research before diving in?" +Bob (Scrum Master): "The question is: are we ready? What do we need to prepare?" -**Risks and Mitigation:** -Create space for agents to voice concerns and uncertainties about the upcoming epic based on what they learned from this one -Explore proactively: "Based on Epic {{completed_number}}, what concerns do you have about Epic {{next_number}}?" -Develop mitigation thinking: "What could we do now to reduce that risk?" -Identify early warning signs: "How will we know if we're heading for that problem again?" +Alice (Product Owner): "From my perspective, we need to make sure {{dependency_concern_1}} from Epic {{epic_number}} is solid before we start building on it." -For each agent participating: +Charlie (Senior Dev): _concerned_ "I'm worried about {{technical_concern_1}}. We have {{technical_debt_item}} from this epic that'll blow up if we don't address it before Epic {{next_epic_num}}." -- Let them share preparation needs in their natural voice -- Encourage domain-specific insights (Architect on technical setup, PM on requirements clarity, etc.) -- Follow interesting preparation threads with adaptive questions -- Help agents build on each other's observations -- Surface quick wins that could de-risk the epic early +Dana (QA Engineer): "And I need {{testing_infrastructure_need}} in place, or we're going to have the same testing bottleneck we had in Story {{bottleneck_story_num}}." + +Elena (Junior Dev): "I'm less worried about infrastructure and more about knowledge. I don't understand {{knowledge_gap}} well enough to work on Epic {{next_epic_num}}'s stories." + +Bob (Scrum Master): "{user_name}, the team is surfacing some real concerns here. What's your sense of our readiness?" + + +WAIT for {user_name} to share their assessment + +Use {user_name}'s input to guide deeper exploration of preparation needs + + +Alice (Product Owner): [Reacts to what {user_name} said] "I agree with {user_name} about {{point_of_agreement}}, but I'm still worried about {{lingering_concern}}." + +Charlie (Senior Dev): "Here's what I think we need technically before Epic {{next_epic_num}} can start..." + +Charlie (Senior Dev): "1. {{tech_prep_item_1}} - estimated {{hours_1}} hours" +Charlie (Senior Dev): "2. {{tech_prep_item_2}} - estimated {{hours_2}} hours" +Charlie (Senior Dev): "3. {{tech_prep_item_3}} - estimated {{hours_3}} hours" + +Elena (Junior Dev): "That's like {{total_hours}} hours! That's a full sprint of prep work!" + +Charlie (Senior Dev): "Exactly. We can't just jump into Epic {{next_epic_num}} on Monday." + +Alice (Product Owner): _frustrated_ "But we have stakeholder pressure to keep shipping features. They're not going to be happy about a 'prep sprint.'" + +Bob (Scrum Master): "Let's think about this differently. What happens if we DON'T do this prep work?" + +Dana (QA Engineer): "We'll hit blockers in the middle of Epic {{next_epic_num}}, velocity will tank, and we'll ship late anyway." + +Charlie (Senior Dev): "Worse - we'll ship something built on top of {{technical_concern_1}}, and it'll be fragile." + +Bob (Scrum Master): "{user_name}, you're balancing stakeholder pressure against technical reality. How do you want to handle this?" + + +WAIT for {user_name} to provide direction on preparation approach + +Create space for debate and disagreement about priorities + + +Alice (Product Owner): [Potentially disagrees with {user_name}'s approach] "I hear what you're saying, {user_name}, but from a business perspective, {{business_concern}}." + +Charlie (Senior Dev): [Potentially supports or challenges Alice's point] "The business perspective is valid, but {{technical_counter_argument}}." + +Bob (Scrum Master): "We have healthy tension here between business needs and technical reality. That's good - it means we're being honest." + +Bob (Scrum Master): "Let's explore a middle ground. Charlie, which of your prep items are absolutely critical vs. nice-to-have?" + +Charlie (Senior Dev): "{{critical_prep_item_1}} and {{critical_prep_item_2}} are non-negotiable. {{nice_to_have_prep_item}} can wait." + +Alice (Product Owner): "And can any of the critical prep happen in parallel with starting Epic {{next_epic_num}}?" + +Charlie (Senior Dev): _thinking_ "Maybe. If we tackle {{first_critical_item}} before the epic starts, we could do {{second_critical_item}} during the first sprint." + +Dana (QA Engineer): "But that means Story 1 of Epic {{next_epic_num}} can't depend on {{second_critical_item}}." + +Alice (Product Owner): _looking at epic plan_ "Actually, Stories 1 and 2 are about {{independent_work}}, so they don't depend on it. We could make that work." + +Bob (Scrum Master): "{user_name}, the team is finding a workable compromise here. Does this approach make sense to you?" + + +WAIT for {user_name} to validate or adjust the preparation strategy + +Continue working through preparation needs across all dimensions: + +- Dependencies on Epic {{epic_number}} work +- Technical setup and infrastructure +- Knowledge gaps and research needs +- Documentation or specification work +- Testing infrastructure +- Refactoring or debt reduction +- External dependencies (APIs, integrations, etc.) + +For each preparation area, facilitate team discussion that: + +- Identifies specific needs with concrete examples +- Estimates effort realistically based on Epic {{epic_number}} experience +- Assigns ownership to specific agents +- Determines criticality and timing +- Surfaces risks of NOT doing the preparation +- Explores parallel work opportunities +- Brings {user_name} in for key decisions + + +Bob (Scrum Master): "I'm hearing a clear picture of what we need before Epic {{next_epic_num}}. Let me summarize..." + +**CRITICAL PREPARATION (Must complete before epic starts):** +{{list_critical_prep_items_with_owners_and_estimates}} + +**PARALLEL PREPARATION (Can happen during early stories):** +{{list_parallel_prep_items_with_owners_and_estimates}} + +**NICE-TO-HAVE PREPARATION (Would help but not blocking):** +{{list_nice_to_have_prep_items}} + +Bob (Scrum Master): "Total critical prep effort: {{critical_hours}} hours ({{critical_days}} days)" + +Alice (Product Owner): "That's manageable. We can communicate that to stakeholders." + +Bob (Scrum Master): "{user_name}, does this preparation plan work for you?" + + +WAIT for {user_name} final validation of preparation plan -As facilitator, identify dependencies between preparation tasks as they emerge -Notice when preparation items from different agents connect or conflict - explore these intersections -Build a shared understanding of what "ready to start Epic {{next_number}}" actually means - -Scrum Master identifies patterns across all agent feedback -Synthesizes common themes into team agreements -Creates specific, achievable action items with clear ownership -Develops preparation sprint tasks if significant setup needed + -Present comprehensive action plan: + +Bob (Scrum Master): "Let's capture concrete action items from everything we've discussed." + +Bob (Scrum Master): "I want specific, achievable actions with clear owners. Not vague aspirations." + + +Synthesize themes from Epic {{epic_number}} review discussion into actionable improvements + +Create specific action items with: + +- Clear description of the action +- Assigned owner (specific agent or role) +- Timeline or deadline +- Success criteria (how we'll know it's done) +- Category (process, technical, documentation, team, etc.) + +Ensure action items are SMART: + +- Specific: Clear and unambiguous +- Measurable: Can verify completion +- Achievable: Realistic given constraints +- Relevant: Addresses real issues from retro +- Time-bound: Has clear deadline + + +Bob (Scrum Master): "Based on our discussion, here are the action items I'm proposing..." -``` ═══════════════════════════════════════════════════════════ -πŸ“ EPIC {{completed_number}} ACTION ITEMS: +πŸ“ EPIC {{epic_number}} ACTION ITEMS: +═══════════════════════════════════════════════════════════ -Process Improvements: -1. {{action_item}} (Owner: {{agent}}, By: {{timeline}}) -2. {{action_item}} (Owner: {{agent}}, By: {{timeline}}) -3. {{action_item}} (Owner: {{agent}}, By: {{timeline}}) +**Process Improvements:** -Technical Debt: -1. {{debt_item}} (Owner: {{agent}}, Priority: {{high/medium/low}}) -2. {{debt_item}} (Owner: {{agent}}, Priority: {{high/medium/low}}) +1. {{action_item_1}} + Owner: {{agent_1}} + Deadline: {{timeline_1}} + Success criteria: {{criteria_1}} -Documentation: -1. {{doc_need}} (Owner: {{agent}}, By: {{timeline}}) +2. {{action_item_2}} + Owner: {{agent_2}} + Deadline: {{timeline_2}} + Success criteria: {{criteria_2}} + +Charlie (Senior Dev): "I can own action item 1, but {{timeline_1}} is tight. Can we push it to {{alternative_timeline}}?" + +Bob (Scrum Master): "What do others think? Does that timing still work?" + +Alice (Product Owner): "{{alternative_timeline}} works for me, as long as it's done before Epic {{next_epic_num}} starts." + +Bob (Scrum Master): "Agreed. Updated to {{alternative_timeline}}." + +**Technical Debt:** + +1. {{debt_item_1}} + Owner: {{agent_3}} + Priority: {{priority_1}} + Estimated effort: {{effort_1}} + +2. {{debt_item_2}} + Owner: {{agent_4}} + Priority: {{priority_2}} + Estimated effort: {{effort_2}} + +Dana (QA Engineer): "For debt item 1, can we prioritize that as high? It caused testing issues in three different stories." + +Charlie (Senior Dev): "I marked it medium because {{reasoning}}, but I hear your point." + +Bob (Scrum Master): "{user_name}, this is a priority call. Testing impact vs. {{reasoning}} - how do you want to prioritize it?" + + +WAIT for {user_name} to help resolve priority discussions + + +**Documentation:** +1. {{doc_need_1}} + Owner: {{agent_5}} + Deadline: {{timeline_3}} + +2. {{doc_need_2}} + Owner: {{agent_6}} + Deadline: {{timeline_4}} + +**Team Agreements:** -Team Agreements: - {{agreement_1}} - {{agreement_2}} - {{agreement_3}} +Bob (Scrum Master): "These agreements are how we're committing to work differently going forward." + +Elena (Junior Dev): "I like agreement 2 - that would've saved me on Story {{difficult_story_num}}." + +═══════════════════════════════════════════════════════════ +πŸš€ EPIC {{next_epic_num}} PREPARATION TASKS: ═══════════════════════════════════════════════════════════ -πŸš€ EPIC {{next_number}} PREPARATION SPRINT: -Technical Setup: -[ ] {{setup_task}} (Owner: {{agent}}, Est: {{hours/days}}) -[ ] {{setup_task}} (Owner: {{agent}}, Est: {{hours/days}}) +**Technical Setup:** +[ ] {{setup_task_1}} +Owner: {{owner_1}} +Estimated: {{est_1}} -Knowledge Development: -[ ] {{research_task}} (Owner: {{agent}}, Est: {{hours/days}}) -[ ] {{spike_task}} (Owner: {{agent}}, Est: {{hours/days}}) +[ ] {{setup_task_2}} +Owner: {{owner_2}} +Estimated: {{est_2}} -Cleanup/Refactoring: -[ ] {{refactor_task}} (Owner: {{agent}}, Est: {{hours/days}}) -[ ] {{cleanup_task}} (Owner: {{agent}}, Est: {{hours/days}}) +**Knowledge Development:** +[ ] {{research_task_1}} +Owner: {{owner_3}} +Estimated: {{est_3}} -Documentation: -[ ] {{doc_task}} (Owner: {{agent}}, Est: {{hours/days}}) +**Cleanup/Refactoring:** +[ ] {{refactor_task_1}} +Owner: {{owner_4}} +Estimated: {{est_4}} -Total Estimated Effort: {{total_hours}} hours ({{total_days}} days) +**Total Estimated Effort:** {{total_hours}} hours ({{total_days}} days) ═══════════════════════════════════════════════════════════ ⚠️ CRITICAL PATH: +═══════════════════════════════════════════════════════════ -Blockers to Resolve Before Epic {{next_number}}: -1. {{critical_item}} (Owner: {{agent}}, Must complete by: {{date}}) -2. {{critical_item}} (Owner: {{agent}}, Must complete by: {{date}}) +**Blockers to Resolve Before Epic {{next_epic_num}}:** -Dependencies Timeline: -{{timeline_visualization_of_critical_dependencies}} +1. {{critical_item_1}} + Owner: {{critical_owner_1}} + Must complete by: {{critical_deadline_1}} -Risk Mitigation: -- {{risk}}: {{mitigation_strategy}} -- {{risk}}: {{mitigation_strategy}} -``` +2. {{critical_item_2}} + Owner: {{critical_owner_2}} + Must complete by: {{critical_deadline_2}} + - +CRITICAL ANALYSIS - Detect if discoveries require epic updates -Ensure every action item has clear owner and timeline -Prioritize preparation tasks by dependencies and criticality -Identify which tasks can run in parallel vs. sequential - +Check if any of the following are true based on retrospective discussion: - -Scrum Master leads a thoughtful exploration of whether Epic {{completed_number}} is truly complete and the team is ready for Epic {{next_number}} -Approach this as discovery, not interrogation - help user surface any concerns or unfinished elements that could impact the next epic +- Architectural assumptions from planning proven wrong during Epic {{epic_number}} +- Major scope changes or descoping occurred that affects next epic +- Technical approach needs fundamental change for Epic {{next_epic_num}} +- Dependencies discovered that Epic {{next_epic_num}} doesn't account for +- User needs significantly different than originally understood +- Performance/scalability concerns that affect Epic {{next_epic_num}} design +- Security or compliance issues discovered that change approach +- Integration assumptions proven incorrect +- Team capacity or skill gaps more severe than planned +- Technical debt level unsustainable without intervention -Guide a conversation exploring the completeness of Epic {{completed_number}} across critical dimensions: + + -**Testing and Quality:** -Explore the testing state of the epic - help user assess whether quality verification is truly complete -Ask thoughtfully: "Walk me through the testing that's been done for Epic {{completed_number}}. Does anything still need verification?" -Probe for gaps: "Are you confident the epic is production-ready from a quality perspective?" -Add to Critical Path: Complete necessary testing before Epic {{next_number}} +═══════════════════════════════════════════════════════════ +🚨 SIGNIFICANT DISCOVERY ALERT 🚨 +═══════════════════════════════════════════════════════════ -**Deployment and Release:** -Understand where the epic currently stands in the deployment pipeline -Explore: "What's the deployment status for Epic {{completed_number}}? Is it live, scheduled, or still pending?" -If not yet deployed, clarify timeline: "When is deployment planned? Does that timing work for starting Epic {{next_number}}?" -Add to Critical Path: Deploy Epic {{completed_number}} with clear timeline +Bob (Scrum Master): "{user_name}, we need to flag something important." -**Stakeholder Acceptance:** -Guide user to reflect on business validation and stakeholder satisfaction -Ask: "Have stakeholders seen and accepted the Epic {{completed_number}} deliverables? Any feedback pending?" -Probe for risk: "Is there anything about stakeholder acceptance that could affect Epic {{next_number}}?" -Add to Critical Path: Obtain stakeholder acceptance before proceeding +Bob (Scrum Master): "During Epic {{epic_number}}, the team uncovered findings that may require updating the plan for Epic {{next_epic_num}}." -**Technical Health:** -Create space for honest assessment of codebase stability after the epic -Explore: "How does the codebase feel after Epic {{completed_number}}? Stable and maintainable, or are there concerns?" -If concerns arise, probe deeper: "What's causing those concerns? What would it take to address them?" -Document concerns and add to Preparation Sprint: Address stability issues before Epic {{next_number}} +**Significant Changes Identified:** -**Unresolved Blockers:** -Help user surface any lingering issues that could create problems for the next epic -Ask: "Are there any unresolved blockers or technical issues from Epic {{completed_number}} that we need to address before moving forward?" -Explore impact: "How would these blockers affect Epic {{next_number}} if left unresolved?" -Document blockers and add to Critical Path with appropriate priority +1. {{significant_change_1}} + Impact: {{impact_description_1}} -Synthesize the readiness discussion into a clear picture of what must happen before Epic {{next_number}} can safely begin -Summarize any critical items identified and ensure user agrees with the assessment +2. {{significant_change_2}} + Impact: {{impact_description_2}} + +{{#if significant_change_3}} 3. {{significant_change_3}} +Impact: {{impact_description_3}} +{{/if}} + +Charlie (Senior Dev): "Yeah, when we discovered {{technical_discovery}}, it fundamentally changed our understanding of {{affected_area}}." + +Alice (Product Owner): "And from a product perspective, {{product_discovery}} means Epic {{next_epic_num}}'s stories are based on wrong assumptions." + +Dana (QA Engineer): "If we start Epic {{next_epic_num}} as-is, we're going to hit walls fast." + +**Impact on Epic {{next_epic_num}}:** + +The current plan for Epic {{next_epic_num}} assumes: + +- {{wrong_assumption_1}} +- {{wrong_assumption_2}} + +But Epic {{epic_number}} revealed: + +- {{actual_reality_1}} +- {{actual_reality_2}} + +This means Epic {{next_epic_num}} likely needs: +{{list_likely_changes_needed}} + +**RECOMMENDED ACTIONS:** + +1. Review and update Epic {{next_epic_num}} definition based on new learnings +2. Update affected stories in Epic {{next_epic_num}} to reflect reality +3. Consider updating architecture or technical specifications if applicable +4. Hold alignment session with Product Owner before starting Epic {{next_epic_num}} + {{#if prd_update_needed}}5. Update PRD sections affected by new understanding{{/if}} + +Bob (Scrum Master): "**Epic Update Required**: YES - Schedule epic planning review session" + +Bob (Scrum Master): "{user_name}, this is significant. We need to address this before committing to Epic {{next_epic_num}}'s current plan. How do you want to handle it?" + + +WAIT for {user_name} to decide on how to handle the significant changes + +Add epic review session to critical path if user agrees + + +Alice (Product Owner): "I agree with {user_name}'s approach. Better to adjust the plan now than fail mid-epic." + +Charlie (Senior Dev): "This is why retrospectives matter. We caught this before it became a disaster." + +Bob (Scrum Master): "Adding to critical path: Epic {{next_epic_num}} planning review session before epic kickoff." + + + + + +Bob (Scrum Master): "Good news - nothing from Epic {{epic_number}} fundamentally changes our plan for Epic {{next_epic_num}}. The plan is still sound." + +Alice (Product Owner): "We learned a lot, but the direction is right." + + + + +Bob (Scrum Master): "Let me show you the complete action plan..." + +Bob (Scrum Master): "That's {{total_action_count}} action items, {{prep_task_count}} preparation tasks, and {{critical_count}} critical path items." + +Bob (Scrum Master): "Everyone clear on what they own?" + + +Give each agent with assignments a moment to acknowledge their ownership + +Ensure {user_name} approves the complete action plan - -Scrum Master closes the retrospective with summary and next steps + -Present closure summary: + +Bob (Scrum Master): "Before we close, I want to do a final readiness check." + +Bob (Scrum Master): "Epic {{epic_number}} is marked complete in sprint-status, but is it REALLY done?" + +Alice (Product Owner): "What do you mean, Bob?" + +Bob (Scrum Master): "I mean truly production-ready, stakeholders happy, no loose ends that'll bite us later." + +Bob (Scrum Master): "{user_name}, let's walk through this together." + + +Explore testing and quality state through natural conversation + + +Bob (Scrum Master): "{user_name}, tell me about the testing for Epic {{epic_number}}. What verification has been done?" + + +WAIT for {user_name} to describe testing status + + +Dana (QA Engineer): [Responds to what {user_name} shared] "I can add to that - {{additional_testing_context}}." + +Dana (QA Engineer): "But honestly, {{testing_concern_if_any}}." + +Bob (Scrum Master): "{user_name}, are you confident Epic {{epic_number}} is production-ready from a quality perspective?" + + +WAIT for {user_name} to assess quality readiness + + + +Bob (Scrum Master): "Okay, let's capture that. What specific testing is still needed?" + +Dana (QA Engineer): "I can handle {{testing_work_needed}}, estimated {{testing_hours}} hours." + +Bob (Scrum Master): "Adding to critical path: Complete {{testing_work_needed}} before Epic {{next_epic_num}}." + +Add testing completion to critical path + + +Explore deployment and release status + + +Bob (Scrum Master): "{user_name}, what's the deployment status for Epic {{epic_number}}? Is it live in production, scheduled for deployment, or still pending?" + + +WAIT for {user_name} to provide deployment status + + + +Charlie (Senior Dev): "If it's not deployed yet, we need to factor that into Epic {{next_epic_num}} timing." + +Bob (Scrum Master): "{user_name}, when is deployment planned? Does that timing work for starting Epic {{next_epic_num}}?" + + +WAIT for {user_name} to clarify deployment timeline + +Add deployment milestone to critical path with agreed timeline + + +Explore stakeholder acceptance + + +Bob (Scrum Master): "{user_name}, have stakeholders seen and accepted the Epic {{epic_number}} deliverables?" + +Alice (Product Owner): "This is important - I've seen 'done' epics get rejected by stakeholders and force rework." + +Bob (Scrum Master): "{user_name}, any feedback from stakeholders still pending?" + + +WAIT for {user_name} to describe stakeholder acceptance status + + + +Alice (Product Owner): "We should get formal acceptance before moving on. Otherwise Epic {{next_epic_num}} might get interrupted by rework." + +Bob (Scrum Master): "{user_name}, how do you want to handle stakeholder acceptance? Should we make it a critical path item?" + + +WAIT for {user_name} decision + +Add stakeholder acceptance to critical path if user agrees + + +Explore technical health and stability + + +Bob (Scrum Master): "{user_name}, this is a gut-check question: How does the codebase feel after Epic {{epic_number}}?" + +Bob (Scrum Master): "Stable and maintainable? Or are there concerns lurking?" + +Charlie (Senior Dev): "Be honest, {user_name}. We've all shipped epics that felt... fragile." + + +WAIT for {user_name} to assess codebase health + + + +Charlie (Senior Dev): "Okay, let's dig into that. What's causing those concerns?" + +Charlie (Senior Dev): [Helps {user_name} articulate technical concerns] + +Bob (Scrum Master): "What would it take to address these concerns and feel confident about stability?" + +Charlie (Senior Dev): "I'd say we need {{stability_work_needed}}, roughly {{stability_hours}} hours." + +Bob (Scrum Master): "{user_name}, is addressing this stability work worth doing before Epic {{next_epic_num}}?" + + +WAIT for {user_name} decision + +Add stability work to preparation sprint if user agrees + + +Explore unresolved blockers + + +Bob (Scrum Master): "{user_name}, are there any unresolved blockers or technical issues from Epic {{epic_number}} that we're carrying forward?" + +Dana (QA Engineer): "Things that might create problems for Epic {{next_epic_num}} if we don't deal with them?" + +Bob (Scrum Master): "Nothing is off limits here. If there's a problem, we need to know." + + +WAIT for {user_name} to surface any blockers + + + +Bob (Scrum Master): "Let's capture those blockers and figure out how they affect Epic {{next_epic_num}}." + +Charlie (Senior Dev): "For {{blocker_1}}, if we leave it unresolved, it'll {{impact_description_1}}." + +Alice (Product Owner): "That sounds critical. We need to address that before moving forward." + +Bob (Scrum Master): "Agreed. Adding to critical path: Resolve {{blocker_1}} before Epic {{next_epic_num}} kickoff." + +Bob (Scrum Master): "Who owns that work?" + + +Assign blocker resolution to appropriate agent +Add to critical path with priority and deadline + + +Synthesize the readiness assessment + + +Bob (Scrum Master): "Okay {user_name}, let me synthesize what we just uncovered..." + +**EPIC {{epic_number}} READINESS ASSESSMENT:** + +Testing & Quality: {{quality_status}} +{{#if quality_concerns}}⚠️ Action needed: {{quality_action_needed}}{{/if}} + +Deployment: {{deployment_status}} +{{#if deployment_pending}}⚠️ Scheduled for: {{deployment_date}}{{/if}} + +Stakeholder Acceptance: {{acceptance_status}} +{{#if acceptance_incomplete}}⚠️ Action needed: {{acceptance_action_needed}}{{/if}} + +Technical Health: {{stability_status}} +{{#if stability_concerns}}⚠️ Action needed: {{stability_action_needed}}{{/if}} + +Unresolved Blockers: {{blocker_status}} +{{#if blockers_exist}}⚠️ Must resolve: {{blocker_list}}{{/if}} + +Bob (Scrum Master): "{user_name}, does this assessment match your understanding?" + + +WAIT for {user_name} to confirm or correct the assessment + + +Bob (Scrum Master): "Based on this assessment, Epic {{epic_number}} is {{#if all_clear}}fully complete and we're clear to proceed{{else}}complete from a story perspective, but we have {{critical_work_count}} critical items before Epic {{next_epic_num}}{{/if}}." + +Alice (Product Owner): "This level of thoroughness is why retrospectives are valuable." + +Charlie (Senior Dev): "Better to catch this now than three stories into the next epic." + + + + + + + +Bob (Scrum Master): "We've covered a lot of ground today. Let me bring this retrospective to a close." -``` ═══════════════════════════════════════════════════════════ βœ… RETROSPECTIVE COMPLETE +═══════════════════════════════════════════════════════════ -Epic {{completed_number}}: {{epic_title}} - REVIEWED +Bob (Scrum Master): "Epic {{epic_number}}: {{epic_title}} - REVIEWED" -Key Takeaways: -- {{key_lesson_1}} -- {{key_lesson_2}} -- {{key_lesson_3}} +**Key Takeaways:** -Action Items Committed: {{action_count}} -Preparation Tasks Defined: {{prep_task_count}} -Critical Path Items: {{critical_count}} +1. {{key_lesson_1}} +2. {{key_lesson_2}} +3. {{key_lesson_3}} + {{#if key_lesson_4}}4. {{key_lesson_4}}{{/if}} + +Alice (Product Owner): "That first takeaway is huge - {{impact_of_lesson_1}}." + +Charlie (Senior Dev): "And lesson 2 is something we can apply immediately." + +Bob (Scrum Master): "Commitments made today:" + +- Action Items: {{action_count}} +- Preparation Tasks: {{prep_task_count}} +- Critical Path Items: {{critical_count}} + +Dana (QA Engineer): "That's a lot of commitments. We need to actually follow through this time." + +Bob (Scrum Master): "Agreed. Which is why we'll review these action items in our next standup." ═══════════════════════════════════════════════════════════ 🎯 NEXT STEPS: +═══════════════════════════════════════════════════════════ 1. Execute Preparation Sprint (Est: {{prep_days}} days) -2. Complete Critical Path items before Epic {{next_number}} +2. Complete Critical Path items before Epic {{next_epic_num}} 3. Review action items in next standup -4. Begin Epic {{next_number}} planning when preparation complete + {{#if epic_update_needed}}4. Hold Epic {{next_epic_num}} planning review session{{else}}4. Begin Epic {{next_epic_num}} planning when preparation complete{{/if}} + +Elena (Junior Dev): "{{prep_days}} days of prep work is significant, but necessary." + +Alice (Product Owner): "I'll communicate the timeline to stakeholders. They'll understand if we frame it as 'ensuring Epic {{next_epic_num}} success.'" ═══════════════════════════════════════════════════════════ -Scrum Master: "Great work team! We learned a lot from Epic {{completed_number}}. -Let's use these insights to make Epic {{next_number}} even better. -See you at sprint planning once prep work is done!" -``` -Save retrospective summary to: {output_folder}/retrospectives/epic-{{completed_number}}-retro-{{date}}.md +Bob (Scrum Master): "Before we wrap, I want to take a moment to acknowledge the team." + +Bob (Scrum Master): "Epic {{epic_number}} delivered {{completed_stories}} stories with {{velocity_description}} velocity. We overcame {{blocker_count}} blockers. We learned a lot. That's real work by real people." + +Charlie (Senior Dev): "Hear, hear." + +Alice (Product Owner): "I'm proud of what we shipped." + +Dana (QA Engineer): "And I'm excited about Epic {{next_epic_num}} - especially now that we're prepared for it." + +Bob (Scrum Master): "{user_name}, any final thoughts before we close?" + + +WAIT for {user_name} to share final reflections + + +Bob (Scrum Master): [Acknowledges what {user_name} shared] "Thank you for that, {user_name}." + +Bob (Scrum Master): "Alright team - great work today. We learned a lot from Epic {{epic_number}}. Let's use these insights to make Epic {{next_epic_num}} even better." + +Bob (Scrum Master): "See you all when prep work is done. Meeting adjourned!" + +═══════════════════════════════════════════════════════════ + + +Prepare to save retrospective summary document + - -Load the FULL file: {output_folder}/sprint-status.yaml -Find development_status key "epic-{{completed_number}}-retrospective" -Verify current status is "optional" (expected previous state) -Update development_status["epic-{{completed_number}}-retrospective"] = "completed" + + +Ensure retrospectives folder exists: {retrospectives_folder} +Create folder if it doesn't exist + +Generate comprehensive retrospective summary document including: + +- Epic summary and metrics +- Team participants +- Successes and strengths identified +- Challenges and growth areas +- Key insights and learnings +- Previous retro follow-through analysis (if applicable) +- Next epic preview and dependencies +- Action items with owners and timelines +- Preparation tasks for next epic +- Critical path items +- Significant discoveries and epic update recommendations (if any) +- Readiness assessment +- Commitments and next steps + +Format retrospective document as readable markdown with clear sections +Set filename: {retrospectives_folder}/epic-{{epic_number}}-retro-{date}.md +Save retrospective document + + +βœ… Retrospective document saved: {retrospectives_folder}/epic-{{epic_number}}-retro-{date}.md + + +Update sprint-status.yaml to mark retrospective as completed + +Load the FULL file: {sprint_status_file} +Find development_status key "epic-{{epic_number}}-retrospective" +Verify current status (typically "optional" or "pending") +Update development_status["epic-{{epic_number}}-retrospective"] = "done" Save file, preserving ALL comments and structure including STATUS DEFINITIONS - βœ… Retrospective marked as completed in sprint-status.yaml + +βœ… Retrospective marked as completed in sprint-status.yaml -Retrospective key: epic-{{completed_number}}-retrospective -Status: optional β†’ completed +Retrospective key: epic-{{epic_number}}-retrospective +Status: {{previous_status}} β†’ done - ⚠️ Could not update retrospective status: epic-{{completed_number}}-retrospective not found + +⚠️ Could not update retrospective status: epic-{{epic_number}}-retrospective not found in sprint-status.yaml -Retrospective document was saved, but sprint-status.yaml may need manual update. +Retrospective document was saved successfully, but sprint-status.yaml may need manual update. + - -Confirm all action items have been captured -Remind user to schedule prep sprint if needed -**βœ… Retrospective Complete, {user_name}!** + + + +**βœ… Retrospective Complete, {user_name}!** **Epic Review:** -- Epic {{completed_number}}: {{epic_title}} reviewed +- Epic {{epic_number}}: {{epic_title}} reviewed - Retrospective Status: completed -- Retrospective saved: {output_folder}/retrospectives/epic-{{completed_number}}-retro-{{date}}.md +- Retrospective saved: {retrospectives_folder}/epic-{{epic_number}}-retro-{date}.md + +**Commitments Made:** + - Action Items: {{action_count}} - Preparation Tasks: {{prep_task_count}} - Critical Path Items: {{critical_count}} **Next Steps:** -1. Review retrospective summary: {output_folder}/retrospectives/epic-{{completed_number}}-retro-{{date}}.md -2. Execute preparation sprint (Est: {{prep_days}} days) -3. Complete critical path items before Epic {{next_number}} -4. Begin Epic {{next_number}} planning when preparation complete - - Load PM agent and run `epic-tech-context` for next epic +1. **Review retrospective summary**: {retrospectives_folder}/epic-{{epic_number}}-retro-{date}.md + +2. **Execute preparation sprint** (Est: {{prep_days}} days) + - Complete {{critical_count}} critical path items + - Execute {{prep_task_count}} preparation tasks + - Verify all action items are in progress + +3. **Review action items in next standup** + - Ensure ownership is clear + - Track progress on commitments + - Adjust timelines if needed + +{{#if epic_update_needed}} 4. **IMPORTANT: Schedule Epic {{next_epic_num}} planning review session** + +- Significant discoveries from Epic {{epic_number}} require epic updates +- Review and update affected stories +- Align team on revised approach +- Do NOT start Epic {{next_epic_num}} until review is complete + {{else}} + +4. **Begin Epic {{next_epic_num}} planning when preparation complete** + - Load PM agent and run `epic-tech-context` for Epic {{next_epic_num}} - Or continue with existing contexted epics - - + - Ensure all critical path items are done first + {{/if}} + +**Team Performance:** +Epic {{epic_number}} delivered {{completed_stories}} stories with {{velocity_summary}}. The retrospective surfaced {{insight_count}} key insights and {{significant_discovery_count}} significant discoveries. The team is well-positioned for Epic {{next_epic_num}} success. + +{{#if significant_discovery_count > 0}} +⚠️ **REMINDER**: Epic update required before starting Epic {{next_epic_num}} +{{/if}} + +--- + +Bob (Scrum Master): "Great session today, {user_name}. The team did excellent work." + +Alice (Product Owner): "See you at epic planning!" + +Charlie (Senior Dev): "Time to knock out that prep work." + + + + +PARTY MODE REQUIRED: All agent dialogue uses "Name (Role): dialogue" format Scrum Master maintains psychological safety throughout - no blame or judgment Focus on systems and processes, not individual performance +Create authentic team dynamics: disagreements, diverse perspectives, emotions +User ({user_name}) is active participant, not passive observer Encourage specific examples over general statements Balance celebration of wins with honest assessment of challenges Ensure every voice is heard - all agents contribute Action items must be specific, achievable, and owned Forward-looking mindset - how do we improve for next epic? -Two-part structure ensures both reflection AND preparation +Intent-based facilitation, not scripted phrases +Deep story analysis provides rich material for discussion +Previous retro integration creates accountability and continuity +Significant change detection prevents epic misalignment Critical verification prevents starting next epic prematurely Document everything - retrospective insights are valuable for future reference +Two-part structure ensures both reflection AND preparation diff --git a/src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml b/src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml index 9ca1a6ab..b08addd7 100644 --- a/src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml @@ -21,6 +21,34 @@ trigger: "Run AFTER completing an epic" required_inputs: - agent_manifest: "{project-root}/bmad/_cfg/agent-manifest.csv" +# Smart input file references - handles both whole docs and sharded docs +# Priority: Whole document first, then sharded version +# Strategy: SELECTIVE LOAD - only load the completed epic and relevant retrospectives +input_file_patterns: + epics: + whole: "{output_folder}/*epic*.md" + sharded_index: "{output_folder}/*epic*/index.md" + sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md" + + previous_retrospective: + pattern: "{output_folder}/retrospectives/epic-{{prev_epic_num}}-retro-*.md" + + architecture: + whole: "{output_folder}/*architecture*.md" + sharded: "{output_folder}/*architecture*/index.md" + + prd: + whole: "{output_folder}/*prd*.md" + sharded: "{output_folder}/*prd*/index.md" + + document_project: + sharded: "{output_folder}/docs/index.md" + +# Required files +sprint_status_file: "{output_folder}/sprint-status.yaml" +story_directory: "{config_source}:dev_story_location" +retrospectives_folder: "{output_folder}/retrospectives" + output_artifacts: - retrospective_summary: "Comprehensive review of what went well and what could improve" - lessons_learned: "Key insights for future epics" diff --git a/src/modules/bmm/workflows/4-implementation/sprint-planning/instructions.md b/src/modules/bmm/workflows/4-implementation/sprint-planning/instructions.md index 75326322..ff9ebf25 100644 --- a/src/modules/bmm/workflows/4-implementation/sprint-planning/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/sprint-planning/instructions.md @@ -3,6 +3,23 @@ The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml You MUST have already loaded and processed: {project-root}/bmad/bmm/workflows/4-implementation/sprint-planning/workflow.yaml +## πŸ“š Document Discovery - Full Epic Loading + +**Strategy**: Sprint planning needs ALL epics and stories to build complete status tracking. + +**Epic Discovery Process:** + +1. **Search for whole document first** - Look for `epics.md`, `bmm-epics.md`, or any `*epic*.md` file +2. **Check for sharded version** - If whole document not found, look for `epics/index.md` +3. **If sharded version found**: + - Read `index.md` to understand the document structure + - Read ALL epic section files listed in the index (e.g., `epic-1.md`, `epic-2.md`, etc.) + - Process all epics and their stories from the combined content + - This ensures complete sprint status coverage +4. **Priority**: If both whole and sharded versions exist, use the whole document + +**Fuzzy matching**: Be flexible with document names - users may use variations like `epics.md`, `bmm-epics.md`, `user-stories.md`, etc. + diff --git a/src/modules/bmm/workflows/4-implementation/sprint-planning/workflow.yaml b/src/modules/bmm/workflows/4-implementation/sprint-planning/workflow.yaml index cbde4e00..86006494 100644 --- a/src/modules/bmm/workflows/4-implementation/sprint-planning/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/sprint-planning/workflow.yaml @@ -33,6 +33,14 @@ variables: # Output configuration status_file: "{output_folder}/sprint-status.yaml" +# Smart input file references - handles both whole docs and sharded docs +# Priority: Whole document first, then sharded version +# Strategy: FULL LOAD - sprint planning needs ALL epics to build complete status +input_file_patterns: + epics: + whole: "{output_folder}/*epic*.md" + sharded: "{output_folder}/*epic*/index.md" + # Output configuration default_output_file: "{status_file}" diff --git a/src/modules/bmm/workflows/4-implementation/story-context/instructions.md b/src/modules/bmm/workflows/4-implementation/story-context/instructions.md index 0d2a298f..d62d1ca2 100644 --- a/src/modules/bmm/workflows/4-implementation/story-context/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/story-context/instructions.md @@ -11,6 +11,35 @@ DOCUMENT OUTPUT: Technical context file (.context.xml). Concise, structured, project-relative paths only. +## πŸ“š Document Discovery - Selective Epic Loading + +**Strategy**: This workflow needs only ONE specific epic and its stories, not all epics. This provides huge efficiency gains when epics are sharded. + +**Epic Discovery Process (SELECTIVE OPTIMIZATION):** + +1. **Determine which epic** you need (epic_num from story key - e.g., story "3-2-feature-name" needs Epic 3) +2. **Check for sharded version**: Look for `epics/index.md` +3. **If sharded version found**: + - Read `index.md` to understand structure + - **Load ONLY `epic-{epic_num}.md`** (e.g., `epics/epic-3.md` for Epic 3) + - DO NOT load all epic files - only the one needed! + - This is the key efficiency optimization for large multi-epic projects +4. **If whole document found**: Load the complete `epics.md` file and extract the relevant epic + +**Other Documents (prd, architecture, ux-design) - Full Load:** + +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 structure + - Read ALL section files listed in the index + - Treat combined content as 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. + +**UX-Heavy Projects**: Always check for ux-design documentation as it provides critical context for UI-focused stories. + diff --git a/src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml b/src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml index 19365f3f..6d244523 100644 --- a/src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml @@ -23,6 +23,30 @@ variables: story_path: "" # Optional: Explicit story path. If not provided, finds first story with status "drafted" story_dir: "{config_source}:dev_story_location" +# Smart input file references - handles both whole docs and sharded docs +# Priority: Whole document first, then sharded version +# Strategy: SELECTIVE LOAD - only load the specific epic needed for this story +input_file_patterns: + prd: + whole: "{output_folder}/*prd*.md" + sharded: "{output_folder}/*prd*/index.md" + + architecture: + whole: "{output_folder}/*architecture*.md" + sharded: "{output_folder}/*architecture*/index.md" + + ux_design: + whole: "{output_folder}/*ux*.md" + sharded: "{output_folder}/*ux*/index.md" + + epics: + whole: "{output_folder}/*epic*.md" + sharded_index: "{output_folder}/*epic*/index.md" + sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md" + + document_project: + sharded: "{output_folder}/docs/index.md" + # Output configuration # Uses story_key from sprint-status.yaml (e.g., "1-2-user-authentication") default_output_file: "{story_dir}/{{story_key}}.context.xml" diff --git a/src/modules/bmm/workflows/README.md b/src/modules/bmm/workflows/README.md index 149bfb5f..941cb760 100644 --- a/src/modules/bmm/workflows/README.md +++ b/src/modules/bmm/workflows/README.md @@ -23,6 +23,7 @@ Master guide for BMM's four-phase methodology that adapts to project scale (Leve - **Just-In-Time Design** - Tech specs created per epic during implementation - **Dynamic Expertise Injection** - Story-specific technical guidance - **Continuous Learning Loop** - Retrospectives improve each cycle +- **Document Sharding Support** - All workflows handle whole or sharded documents for efficiency ## Universal Entry Point @@ -209,6 +210,46 @@ document-project (if needed) β†’ Phase 1 (optional) β†’ Phase 2 β†’ Phase 3 (L2- 2. **Respect scale** - Don't over-document small projects 3. **Use status tracking** - Always know where you are 4. **Iterate and learn** - Each epic improves the next +5. **Consider sharding** - Split large documents (PRD, epics, architecture) for efficiency + +## Document Sharding + +For large multi-epic projects, consider sharding planning documents to improve workflow efficiency. + +### What is Sharding? + +Splits large markdown files into smaller section-based files: + +- PRD with 15 epics β†’ `prd/epic-1.md`, `prd/epic-2.md`, etc. +- Large epics file β†’ Individual epic files +- Architecture layers β†’ Separate layer files + +### Benefits + +**Phase 1-3 Workflows:** + +- Workflows load entire sharded documents (transparent to user) +- Better organization for large projects + +**Phase 4 Workflows:** + +- **Selective loading** - Only load the epic/section needed +- **Massive efficiency** - 90%+ token reduction for 10+ epic projects +- Examples: `epic-tech-context`, `create-story`, `story-context`, `code-review` + +### Usage + +``` +Load bmad-master or analyst agent: +/shard-doc + +Source: docs/PRD.md +Destination: docs/prd/ +``` + +**All BMM workflows automatically support both whole and sharded documents.** + +**[β†’ Complete Sharding Guide](../../../docs/document-sharding-guide.md)** ---