From 0416f72d7da75cd92a3120b814fb4678d24453a5 Mon Sep 17 00:00:00 2001 From: DJ Date: Fri, 3 Apr 2026 21:12:09 -0700 Subject: [PATCH] fix: make downstream workflows read deferred-work.md from code reviews Closes #2199. Code reviews write deferred items to deferred-work.md but no downstream workflow ever reads them back, causing tech debt to accumulate silently. This change integrates deferred-work.md into the three key workflows that should consume it: - bmad-create-story: loads deferred-work.md in step 2, matches items by file path against the new story's scope, and folds overlapping items into the story as Dev Notes and Tasks subtasks - bmad-sprint-status: parses the deferred backlog, adds severity counts to the status display, and raises risks for large or high-priority backlogs - bmad-retrospective: analyzes deferred items created vs resolved during the epic, surfaces carried-forward stats in the metrics summary, and includes the deferred work summary in the saved retro document Co-Authored-By: Claude Opus 4.6 (1M context) --- .../bmad-create-story/workflow.md | 56 +++++++++++++++++++ .../bmad-retrospective/workflow.md | 45 +++++++++++++++ .../bmad-sprint-status/workflow.md | 22 ++++++++ 3 files changed, 123 insertions(+) diff --git a/src/bmm-skills/4-implementation/bmad-create-story/workflow.md b/src/bmm-skills/4-implementation/bmad-create-story/workflow.md index 0acd8666b..3d0b3ba36 100644 --- a/src/bmm-skills/4-implementation/bmad-create-story/workflow.md +++ b/src/bmm-skills/4-implementation/bmad-create-story/workflow.md @@ -34,6 +34,7 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve: - `ux_file` = `{planning_artifacts}/*ux*.md` - `story_title` = "" (will be elicited if not derivable) - `project_context` = `**/project-context.md` (load if exists) +- `deferred_work_file` = `{implementation_artifacts}/deferred-work.md` - `default_output_file` = `{implementation_artifacts}/{{story_key}}.md` ### Input Files @@ -232,6 +233,43 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve: all learnings that could impact current story implementation + + + Load {deferred_work_file} completely + Parse all deferred items, extracting for each: + - File paths mentioned (e.g., [src/foo.ts:42]) + - Category (bug, security, tech-debt, style, etc.) + - Originating review (e.g., "Deferred from: code review of story-2.3") + - Description text + + + From epics content and architecture analysis, build a list of files this story will likely touch: + - Files explicitly mentioned in story requirements + - Files in modules/directories related to the story's feature area + - Files that share dependencies with story components + + + Match deferred items against the story's file list: + - EXACT match: deferred item references a file the story will modify + - DIRECTORY match: deferred item is in the same directory/module + - COMPONENT match: deferred item affects a component the story depends on + + + + Store {{matched_deferred_items}} for inclusion in the story file + Classify matches by priority: + - HIGH: security fixes, bugs in files this story will modify + - MEDIUM: tech-debt in the same module, performance issues in touched code + - LOW: style issues, minor refactors in adjacent files + + 📋 Found {{matched_count}} deferred work items relevant to this story from previous code reviews + + + + Set {{matched_deferred_items}} = empty + + + @@ -324,6 +362,24 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve: git_intelligence_summary + + + In the Dev Notes section, add a subsection: + +### Deferred Items to Address + +The following items were deferred from previous code reviews and overlap with files/modules this story will touch. Address these during implementation where practical. + +{{#each matched_deferred_items}} +- **[{{priority}}]** {{description}} `[{{file_ref}}]` — _from {{origin_review}}_ +{{/each}} + + + In the Tasks/Subtasks section, add corresponding subtasks for HIGH-priority deferred items: + - [ ] [Deferred] {{item_title}} [{{file_ref}}] (from previous review) + + + latest_tech_information diff --git a/src/bmm-skills/4-implementation/bmad-retrospective/workflow.md b/src/bmm-skills/4-implementation/bmad-retrospective/workflow.md index 3f56f728c..417ec2288 100644 --- a/src/bmm-skills/4-implementation/bmad-retrospective/workflow.md +++ b/src/bmm-skills/4-implementation/bmad-retrospective/workflow.md @@ -38,6 +38,7 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve: ### Paths - `sprint_status_file` = `{implementation_artifacts}/sprint-status.yaml` +- `deferred_work_file` = `{implementation_artifacts}/deferred-work.md` ### Input Files @@ -48,6 +49,7 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve: | architecture | System architecture for context | whole: `{planning_artifacts}/*architecture*.md`, sharded: `{planning_artifacts}/*architecture*/*.md` | FULL_LOAD | | prd | Product requirements for context | whole: `{planning_artifacts}/*prd*.md`, sharded: `{planning_artifacts}/*prd*/*.md` | FULL_LOAD | | document_project | Brownfield project documentation (optional) | sharded: `{planning_artifacts}/*.md` | INDEX_GUIDED | +| deferred_work | Deferred items from code reviews | `{deferred_work_file}` | FULL_LOAD (optional) | ### Required Inputs @@ -247,6 +249,41 @@ Charlie (Senior Dev): "Good idea - those dev notes always have gold in them." - Track bug patterns or regression issues - Document test coverage gaps +**Deferred Work Backlog Analysis:** + + + Load {deferred_work_file} completely + Parse all deferred items and compute: + + - Total items deferred across all reviews + - Items originating from this epic's stories (match by "Deferred from: code review of story-{{epic_number}}.*") + - Items originating from previous epics (carried forward) + - Items that were addressed during this epic (cross-reference with story file lists and git history) + - Items still outstanding + + Classify outstanding items by severity: + + - Security issues: count and list + - Bugs: count and list + - Tech-debt: count and list + - Style/minor: count and list + + Store deferred work stats: + + - {{deferred_created_this_epic}}: items deferred during this epic's reviews + - {{deferred_resolved_this_epic}}: items addressed during this epic + - {{deferred_carried_forward}}: items still outstanding + - {{deferred_high_priority}}: security + bug items still outstanding + + IF {{deferred_carried_forward}} > 0: flag for discussion in retrospective as a quality concern + IF {{deferred_high_priority}} > 0: flag as critical — high-priority items are aging without resolution + + + + Set {{deferred_created_this_epic}} = 0, {{deferred_resolved_this_epic}} = 0, {{deferred_carried_forward}} = 0 + Note: no deferred work file found — either no code reviews ran or all findings were resolved inline + + Synthesize patterns across all stories: **Common Struggles:** @@ -507,6 +544,13 @@ Quality and Technical: - Test coverage: {{coverage_info}} - Production incidents: {{incident_count}} +Deferred Work (from code reviews): + +- Created this epic: {{deferred_created_this_epic}} +- Resolved this epic: {{deferred_resolved_this_epic}} +- Carried forward: {{deferred_carried_forward}}{{#if deferred_high_priority}} +- ⚠️ High-priority outstanding: {{deferred_high_priority}} (security/bugs){{/if}} + Business Outcomes: - Goals achieved: {{goals_met}}/{{total_goals}} @@ -1352,6 +1396,7 @@ Bob (Scrum Master): "See you all when prep work is done. Meeting adjourned!" - Action items with owners and timelines - Preparation tasks for next epic - Critical path items +- Deferred work summary (items created, resolved, carried forward, high-priority outstanding) - Significant discoveries and epic update recommendations (if any) - Readiness assessment - Commitments and next steps diff --git a/src/bmm-skills/4-implementation/bmad-sprint-status/workflow.md b/src/bmm-skills/4-implementation/bmad-sprint-status/workflow.md index 1def1c8f3..4da2199da 100644 --- a/src/bmm-skills/4-implementation/bmad-sprint-status/workflow.md +++ b/src/bmm-skills/4-implementation/bmad-sprint-status/workflow.md @@ -21,12 +21,14 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve: ### Paths - `sprint_status_file` = `{implementation_artifacts}/sprint-status.yaml` +- `deferred_work_file` = `{implementation_artifacts}/deferred-work.md` ### Input Files | Input | Path | Load Strategy | |-------|------|---------------| | Sprint status | `{sprint_status_file}` | FULL_LOAD | +| Deferred work | `{deferred_work_file}` | FULL_LOAD (optional) | ### Context @@ -118,6 +120,18 @@ Enter corrections (e.g., "1=in-progress, 2=backlog") or "skip" to continue witho - IF `last_updated` timestamp is more than 7 days old (or `last_updated` is missing, fall back to `generated`): warn "sprint-status.yaml may be stale" - IF any story key doesn't match an epic pattern (e.g., story "5-1-..." but no "epic-5"): warn "orphaned story detected" - IF any epic has status in-progress but has no associated stories: warn "in-progress epic has no stories" + +Analyze deferred work backlog (if {deferred_work_file} exists): + + + Parse all deferred items from {deferred_work_file} + Count total deferred items + Group items by originating review/story + Classify items by severity if identifiable (security, bug, tech-debt, style) + Store counts: {{deferred_total}}, {{deferred_high}} (security/bug), {{deferred_medium}} (tech-debt), {{deferred_low}} (style/minor) + IF {{deferred_total}} > 20: add risk "Deferred work backlog is large ({{deferred_total}} items) — consider triaging with SM agent" + IF {{deferred_high}} > 0: add risk "{{deferred_high}} high-priority deferred items (security/bugs) need attention" + @@ -144,6 +158,10 @@ Enter corrections (e.g., "1=in-progress, 2=backlog") or "skip" to continue witho **Epics:** backlog {{epic_backlog}}, in-progress {{epic_in_progress}}, done {{epic_done}} +{{#if deferred_total}} +**Deferred Work:** {{deferred_total}} items ({{deferred_high}} high, {{deferred_medium}} medium, {{deferred_low}} low) +{{/if}} + **Next Recommendation:** /bmad:bmm:workflows:{{next_workflow_id}} ({{next_story_id}}) {{#if risks}} @@ -208,6 +226,10 @@ If the command targets a story, set `story_key={{next_story_id}}` when prompted. epic_in_progress = {{epic_in_progress}} epic_done = {{epic_done}} risks = {{risks}} + deferred_total = {{deferred_total}} + deferred_high = {{deferred_high}} + deferred_medium = {{deferred_medium}} + deferred_low = {{deferred_low}} Return to caller