ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/src/modules/bmm/workflows/4-implementation/code-review
History
Brian Madison 3d4ea5ffd2 feat: add universal document sharding support with dual-strategy loading 
Implement comprehensive document sharding system across all BMM workflows enabling 90%+ token savings for large multi-epic projects through selective loading optimization.

## Document Sharding System

### Core Features
- **Universal Support**: All 12 BMM workflows (Phase 1-4) handle both whole and sharded documents
- **Dual Loading Strategy**: Full Load (Phase 1-3) vs Selective Load (Phase 4)
- **Automatic Discovery**: Workflows detect format transparently (whole → sharded priority)
- **Efficiency Optimization**: 90%+ token reduction for 10+ epic projects in Phase 4

### Implementation Details

**Phase 1-3 Workflows (7 workflows) - Full Load Strategy:**
- product-brief, prd, gdd, create-ux-design, tech-spec, architecture, solutioning-gate-check
- Load entire sharded documents when present
- Transparent to user experience
- Better organization for large projects

**Phase 4 Workflows (5 workflows) - Selective Load Strategy:**
- sprint-planning (Full Load exception - needs all epics)
- epic-tech-context, create-story, story-context, code-review (Selective Load)
- Load ONLY the specific epic needed (e.g., epic-3.md for Epic 3 stories)
- Massive efficiency: Skip loading 9 other epics in 10-epic project

### Workflow Enhancements

**Added to all workflows:**
- `input_file_patterns` in workflow.yaml with wildcard discovery
- Document Discovery section in instructions.md
- Support for sharded index + section files
- Brownfield `docs/index.md` support

**Pattern standardization:**
```yaml
input_file_patterns:
  document:
    whole: "{output_folder}/*doc*.md"
    sharded: "{output_folder}/*doc*/index.md"
    sharded_single: "{output_folder}/*doc*/section-{{id}}.md"  # Selective load
```

### Retrospective Workflow Major Overhaul

Transformed retrospective into immersive, interactive team experience:

**Epic Discovery Priority (Fixed):**
- Priority 1: Check sprint-status.yaml for last completed epic
- Priority 2: Ask user directly
- Priority 3: Scan stories folder (last resort)

**New Capabilities:**
- Deep story analysis: Extract dev notes, mistakes, review feedback, lessons learned
- Previous retro integration: Track action items, verify lessons applied
- Significant change detection: Alert when discoveries require epic updates
- Intent-based facilitation: Natural conversation vs scripted phrases
- Party mode protocol: Clear speaker identification (Name (Role): dialogue)
- Team dynamics: Drama, disagreements, diverse perspectives, authentic conflict

**Structure:**
- 12 whole-number steps (no decimals)
- Highly interactive with constant user engagement
- Cross-references previous retro for accountability
- Synthesizes patterns across all stories
- Detects architectural assumption changes

## Documentation

**Created:**
- `docs/document-sharding-guide.md` - Comprehensive 300+ line guide
  - What is sharding, when to use it (token thresholds)
  - How sharding works (discovery system, loading strategies)
  - Using shard-doc tool
  - Full Load vs Selective Load patterns
  - Complete examples and troubleshooting
  - Custom workflow integration patterns

**Updated:**
- `README.md` - Added Document Sharding feature section
- `docs/index.md` - Added under Advanced Topics → Optimization
- `src/modules/bmm/workflows/README.md` - Added sharding section with usage
- `src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md` - Added complete implementation patterns for workflow builders

**Documentation levels:**
1. Overview (README.md) - Quick feature highlight
2. User guide (BMM workflows README) - Practical usage
3. Reference (document-sharding-guide.md) - Complete details
4. Builder guide (workflow-creation-guide.md) - Implementation patterns

## Efficiency Gains

**Example: 10-Epic Project**

Before sharding:
- epic-tech-context for Epic 3: Load all 10 epics (~50k tokens)
- create-story for Epic 3: Load all 10 epics (~50k tokens)
- story-context for Epic 3: Load all 10 epics (~50k tokens)

After sharding with selective load:
- epic-tech-context for Epic 3: Load Epic 3 only (~5k tokens) = 90% reduction
- create-story for Epic 3: Load Epic 3 only (~5k tokens) = 90% reduction
- story-context for Epic 3: Load Epic 3 only (~5k tokens) = 90% reduction

## Breaking Changes

None - fully backward compatible. Workflows work with existing whole documents.

## Files Changed

**Workflows Updated (25 files):**
- 7 Phase 1-3 workflows: Added full load sharding support
- 5 Phase 4 workflows: Added selective load sharding support
- 1 retrospective workflow: Complete overhaul with sharding support

**Documentation (5 files):**
- Created: document-sharding-guide.md
- Updated: README.md, docs/index.md, BMM workflows README, BMB workflow-creation-guide
- Removed: Old conversion report (obsolete)

## Future Extensibility

- BMB workflows now aware of sharding patterns
- Custom modules can easily implement sharding support
- Standard patterns documented for consistency
- No need to explain concept in future development
 		2025-11-02 00:13:33 -05:00
..
README.md story review was missing detailed instructions to review AC and task adherance. 2025-10-28 08:51:58 -05:00
backlog_template.md story review was missing detailed instructions to review AC and task adherance. 2025-10-28 08:51:58 -05:00
checklist.md story review was missing detailed instructions to review AC and task adherance. 2025-10-28 08:51:58 -05:00
instructions.md feat: add universal document sharding support with dual-strategy loading 2025-11-02 00:13:33 -05:00
workflow.yaml feat: add universal document sharding support with dual-strategy loading 2025-11-02 00:13:33 -05:00

README.md

Review Story (Senior Developer Code Review)

Perform an AI-driven Senior Developer Code Review on a story flagged "Ready for Review". The workflow ingests the story, its Story Context, and the epic’s Tech Spec, consults local docs, uses enabled MCP servers for up-to-date best practices (with web search fallback), and appends structured review notes to the story.

What It Does

  • Auto-discovers the target story or accepts an explicit story_path
  • Verifies the story is in a reviewable state (e.g., Ready for Review/Review)
  • Loads Story Context (from Dev Agent Record → Context Reference or auto-discovery)
  • Locates the epic Tech Spec and relevant architecture/standards docs
  • Uses MCP servers for best-practices and security references; falls back to web search
  • Reviews implementation vs Acceptance Criteria, Tech Spec, and repo standards
  • Evaluates code quality, security, and test coverage
  • Appends a "Senior Developer Review (AI)" section to the story with findings and action items
  • Optionally updates story Status based on outcome

How to Invoke

  • Tell the Dev Agent to perform a *code-review after loading the dev agent. This is a context intensive operation so this should not be done in the same context as a just completed dev session - clear the context, reload the dev, then run code-review!

Inputs and Variables

  • story_path (optional): Explicit path to a story file
  • story_dir (from config): {project-root}/bmad/bmm/config.yaml → dev_story_location
  • allow_status_values: Defaults include Ready for Review, Review
  • auto_discover_context (default: true)
  • auto_discover_tech_spec (default: true)
  • tech_spec_glob_template: tech-spec-epic-{{epic_num}}*.md
  • arch_docs_search_dirs: Defaults to docs/ and outputs/
  • enable_mcp_doc_search (default: true)
  • enable_web_fallback (default: true)
  • update_status_on_result (default: false)

Story Updates

  • Appends a section titled: Senior Developer Review (AI) at the end
  • Adds a Change Log entry: "Senior Developer Review notes appended"
  • If enabled, updates Status based on outcome

Persistence and Backlog

To ensure review findings become actionable work, the workflow can persist action items to multiple targets (configurable):

  • Story tasks: Inserts unchecked items under Tasks / Subtasks in a "Review Follow-ups (AI)" subsection so dev-story can pick them up next.
  • Story review section: Keeps a full list under "Senior Developer Review (AI) → Action Items".
  • Backlog file: Appends normalized rows to docs/backlog.md (created if missing) for cross-cutting or longer-term improvements.
  • Epic follow-ups: If an epic Tech Spec is found, appends to its Post-Review Follow-ups section.

Configure via workflow.yaml variables:

  • persist_action_items (default: true)
  • persist_targets: story_tasks, story_review_section, backlog_file, epic_followups
  • backlog_file (default: {project-root}/docs/backlog.md)
  • update_epic_followups (default: true)
  • epic_followups_section_title (default: Post-Review Follow-ups)

Routing guidance:

  • Put must-fix items to ship the story into the story’s tasks.
  • Put same-epic but non-blocking improvements into the epic Tech Spec follow-ups.
  • Put cross-cutting, future, or refactor work into the backlog file.

Related Workflows

  • dev-story — Implements tasks/subtasks and can act on review action items
  • story-context — Generates Story Context for a single story
  • tech-spec — Generates epic Tech Spec documents

Part of the BMAD Method v6 — Implementation Phase