Skip to content

fix: read deferred-work.md in create-story, sprint-status, and retrospective #2202

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
don-petry wants to merge 2 commits into
base: main
Choose a base branch
from
+143 −1
Open

fix: read deferred-work.md in create-story, sprint-status, and retrospective #2202

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0416f72
fix: make downstream workflows read deferred-work.md from code reviews
Apr 4, 2026
beeccbc
fix: address review feedback on deferred-work read-back workflows
Apr 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 68 additions & 0 deletions src/bmm-skills/4-implementation/bmad-create-story/workflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`

Comment on lines 35 to 39
Copy link

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

deferred_work_file is introduced, but the create-story discover-inputs.md protocol only loads files declared in the workflow’s Input Files table. Without adding {deferred_work_file} as an (optional) input there, deferred-work may not be loaded into context consistently, and the later "Load {deferred_work_file}" step relies on ad-hoc behavior. Add an Input Files row for deferred work (optional) or explicitly document/ensure it’s loaded outside the discovery protocol.

Copilot uses AI. Check for mistakes.
### Input Files
Expand All @@ -44,6 +45,7 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
| architecture | Architecture (fallback - epics file should have relevant sections) | whole: `{planning_artifacts}/*architecture*.md`, sharded: `{planning_artifacts}/*architecture*/*.md` | SELECTIVE_LOAD |
| ux | UX design (fallback - epics file should have relevant sections) | whole: `{planning_artifacts}/*ux*.md`, sharded: `{planning_artifacts}/*ux*/*.md` | SELECTIVE_LOAD |
| epics | Enhanced epics+stories file with BDD and source hints | whole: `{planning_artifacts}/*epic*.md`, sharded: `{planning_artifacts}/*epic*/*.md` | SELECTIVE_LOAD |
| deferred_work | Deferred items from code reviews (optional) | `{deferred_work_file}` | FULL_LOAD (optional) |

---

Expand Down Expand Up @@ -232,6 +234,54 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
all learnings that could impact current story implementation</action>
</check>

<!-- Deferred work items analysis -->
<check if="{deferred_work_file} exists AND has content">
<action>Load {deferred_work_file} completely</action>
<action>Parse all deferred items. The file uses level-2 headings produced by bmad-code-review:
`## Deferred from: code review of story-X.Y (YYYY-MM-DD)`
Each heading is followed by bullet items (one per deferred finding).

For each bullet item extract:
- File paths mentioned (e.g., [src/foo.ts:42])
- Originating review: the heading text above the bullet (e.g., "code review of story-2.3 (2026-03-18)")
- Description text: the bullet content
- Category: if the producer included an explicit category, use it; otherwise derive heuristically from keywords in the description:
- "security" / "auth" / "injection" / "XSS" / "CSRF" → security
- "bug" / "crash" / "error" / "null" / "undefined" / "NaN" → bug
- "performance" / "slow" / "N+1" / "cache" → performance
- "style" / "lint" / "formatting" / "naming" → style
- otherwise → tech-debt
- Set `inferred_category = true` when the category was derived heuristically
</action>

<action>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
</action>

<action>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
</action>

<check if="overlapping deferred items found">
<action>Store {{matched_deferred_items}} for inclusion in the story file</action>
<action>Set {{matched_count}} = number of items in {{matched_deferred_items}}</action>
<action>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
</action>
<output>📋 Found {{matched_count}} deferred work items relevant to this story from previous code reviews</output>
</check>
Comment on lines +269 to +278
Copy link

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

{{matched_count}} is referenced in the output, but it’s never set anywhere in the workflow. This will render as blank/undefined. Compute and store a matched count when building matched_deferred_items (or derive it from the collection length).

Copilot uses AI. Check for mistakes.

<check if="no overlapping deferred items found">
<action>Set {{matched_deferred_items}} = empty</action>
</check>
</check>

<!-- Git intelligence for previous work patterns -->
<check
if="previous story exists AND git repository detected">
Expand Down Expand Up @@ -324,6 +374,24 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
<template-output file="{default_output_file}">git_intelligence_summary</template-output>
</check>

<!-- Deferred work items from previous code reviews -->
<check if="{{matched_deferred_items}} is not empty">
<action>In the Dev Notes section, add a subsection:</action>
<template-output file="{default_output_file}">
### 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}}
</template-output>

<action>In the Tasks/Subtasks section, add corresponding subtasks for HIGH-priority deferred items:
- [ ] [Deferred] {{description}} [{{file_ref}}] (from previous review)
</action>
Comment on lines +390 to +392
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Apr 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Undefined {{item_title}} will produce empty deferred subtasks.

Line 379 uses {{item_title}}, but this field is never extracted in the deferred parsing step. Use {{description}} (or explicitly extract item_title) to avoid blank task text.

Suggested fix 
-    <action>In the Tasks/Subtasks section, add corresponding subtasks for HIGH-priority deferred items:
-      - [ ] [Deferred] {{item_title}} [{{file_ref}}] (from previous review)
-    </action>
+    <action>In the Tasks/Subtasks section, add corresponding subtasks for HIGH-priority deferred items:
+      - [ ] [Deferred] {{description}} [{{file_ref}}] (from {{origin_review}})
+    </action>
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@src/bmm-skills/4-implementation/bmad-create-story/workflow.md` around lines
378 - 380, The deferred-subtask template is using an undefined template variable
{{item_title}} which yields blank task text; update the Tasks/Subtasks section
so the line uses {{description}} instead of {{item_title}} (or modify the
deferred parsing step to extract and populate item_title from the parsed item)
for HIGH-priority deferred items (the template line: "- [ ] [Deferred]
{{item_title}} [{{file_ref}}] (from previous review)"). Ensure the change is
applied wherever deferred subtasks are generated so the task text is populated.

</check>

<!-- Latest technical specifics -->
<check if="web research completed">
<template-output file="{default_output_file}">latest_tech_information</template-output>
Expand Down
45 changes: 45 additions & 0 deletions src/bmm-skills/4-implementation/bmad-retrospective/workflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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:**

<check if="{deferred_work_file} exists AND has content">
<action>Load {deferred_work_file} completely</action>
<action>Parse all deferred items and compute:</action>

- Total items deferred across all reviews
- Items originating from this epic's stories (match by level-2 headings: `## Deferred from: code review of story-{{epic_number}}.* (YYYY-MM-DD)`)
- Items originating from previous epics (carried forward — headings referencing other epic numbers)
- Items that were addressed during this epic (cross-reference with story file lists and git history)
- Items still outstanding

<action>Classify outstanding items by severity. If the producer included an explicit category use it; otherwise derive heuristically from description keywords (security/auth/injection → security; bug/crash/error/null → bug; performance/slow/cache → performance; style/lint/naming → style; default → tech-debt):</action>

- Security issues: count and list
- Bugs: count and list
- Tech-debt: count and list
- Style/minor: count and list

<action>Store deferred work stats:</action>

- {{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

<action>IF {{deferred_carried_forward}} > 0: flag for discussion in retrospective as a quality concern</action>
<action>IF {{deferred_high_priority}} > 0: flag as critical — high-priority items are aging without resolution</action>
</check>

<check if="{deferred_work_file} does NOT exist or is empty">
<action>Set {{deferred_created_this_epic}} = 0, {{deferred_resolved_this_epic}} = 0, {{deferred_carried_forward}} = 0</action>
<action>Note: no deferred work file found — either no code reviews ran or all findings were resolved inline</action>
</check>

<action>Synthesize patterns across all stories:</action>

**Common Struggles:**
Expand Down Expand Up @@ -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}}
Expand Down Expand Up @@ -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
Expand Down
31 changes: 30 additions & 1 deletion src/bmm-skills/4-implementation/bmad-sprint-status/workflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -118,6 +120,25 @@ 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"

<action>Analyze deferred work backlog (if {deferred_work_file} exists):</action>

<check if="{deferred_work_file} exists AND has content">
<action>Parse all deferred items from {deferred_work_file}. The file uses level-2 headings produced by bmad-code-review:
`## Deferred from: code review of story-X.Y (YYYY-MM-DD)`
Each heading is followed by bullet items (one per deferred finding).
</action>
<action>Count total deferred items (bullet items, not headings)</action>
<action>Group items by originating review/story (derived from the heading above each group)</action>
<action>Classify items by severity: if the item includes an explicit category use it; otherwise derive heuristically from description keywords (security/auth/injection → security; bug/crash/error/null → bug; performance/slow/cache → performance; style/lint/naming → style; default → tech-debt)</action>
<action>Store counts: {{deferred_total}}, {{deferred_high}} (security/bug), {{deferred_medium}} (tech-debt/performance), {{deferred_low}} (style/minor)</action>
<action>IF {{deferred_total}} > 20: add risk "Deferred work backlog is large ({{deferred_total}} items) — consider triaging with SM agent"</action>
<action>IF {{deferred_high}} > 0: add risk "{{deferred_high}} high-priority deferred items (security/bugs) need attention"</action>
</check>

<check if="{deferred_work_file} does NOT exist OR is empty">
<action>Set {{deferred_total}} = 0, {{deferred_high}} = 0, {{deferred_medium}} = 0, {{deferred_low}} = 0</action>
</check>
</step>

<step n="3" goal="Select next action recommendation">
Expand All @@ -144,6 +165,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}}
Expand Down Expand Up @@ -195,7 +220,7 @@ If the command targets a story, set `story_key={{next_story_id}}` when prompted.
<!-- ========================= -->

<step n="20" goal="Data mode output">
<action>Load and parse {sprint_status_file} same as Step 2</action>
<action>Load and parse {sprint_status_file} same as Step 2 (including deferred work analysis — set deferred counts to 0 when file is missing/empty)</action>
<action>Compute recommendation same as Step 3</action>
<template-output>next_workflow_id = {{next_workflow_id}}</template-output>
<template-output>next_story_id = {{next_story_id}}</template-output>
Expand All @@ -208,6 +233,10 @@ If the command targets a story, set `story_key={{next_story_id}}` when prompted.
<template-output>epic_in_progress = {{epic_in_progress}}</template-output>
<template-output>epic_done = {{epic_done}}</template-output>
<template-output>risks = {{risks}}</template-output>
<template-output>deferred_total = {{deferred_total}}</template-output>
<template-output>deferred_high = {{deferred_high}}</template-output>
<template-output>deferred_medium = {{deferred_medium}}</template-output>
<template-output>deferred_low = {{deferred_low}}</template-output>
Comment on lines 235 to +239
Copy link

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Deferred-work variables are only set when {deferred_work_file} exists and has content, but in data mode the workflow always emits deferred_* template outputs. When the file is missing/empty this will output undefined values and may confuse downstream callers. Consider setting defaults (0) when deferred-work.md is absent/empty, or guard these template-output lines behind a check.

Copilot uses AI. Check for mistakes.
<action>Return to caller</action>
</step>

Expand Down