fix(skill): clean up bmad-create-epics-and-stories validation findings#1989
Merged
fix(skill): clean up bmad-create-epics-and-stories validation findings#1989
Conversation
Remove name/description from step frontmatter (STEP-06) and add missing HALT before user menu in step-04-final-validation (STEP-04). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
🤖 Augment PR SummarySummary: Cleans up the 🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
📝 WalkthroughWalkthroughThe PR removes YAML frontmatter metadata (name and description fields) from three workflow step markdown files and adds a HALT instruction pause to the final validation step for user confirmation. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (6)
src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-04-final-validation.md (6)
116-123: 🛠️ Refactor suggestion | 🟠 MajorMissing validation results summary.
Line 123 announces "All validations complete!" but provides no summary of what was actually validated. The user has no way to verify that all six validation sections (FR Coverage, Architecture, Story Quality, Epic Structure, Dependencies, Complete and Save) were executed.
Before presenting the completion menu, the agent should summarize:
- Number of FRs validated for coverage
- Number of stories checked for quality
- Dependency validation results
- Architecture compliance findings
- Any warnings or notes
This builds user confidence and provides a record of the validation scope.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-04-final-validation.md` around lines 116 - 123, The final validation step currently prints "All validations complete!" without any results; update the Step 04 finalization flow in step-04-final-validation.md to insert a concise validation summary before the "Present Final Menu" section that lists: the number of FRs validated for coverage (FR Coverage), the number of stories checked for quality (Story Quality), dependency validation outcomes (Dependencies) including any unresolved items, architecture compliance findings (Architecture) and any warnings/notes (Epic Structure and Complete and Save); ensure the summary references those six validation sections by name and presents numeric counts and short status lines so the user can verify what was executed before the completion menu is shown.
48-58:⚠️ Potential issue | 🟠 MajorFR Coverage Validation lacks Requirements Inventory location.
Line 54 instructs the agent to "Go through each FR from the Requirements Inventory" but nowhere in this step file (or in Context Boundaries, lines 39-45) is the location, format, or access method for this inventory specified.
Is it:
- Part of the PRD document?
- A separate requirements.yaml file?
- Embedded in the architecture document?
- A table, list, or structured format?
Without this information, the agent cannot execute the validation. The step needs to specify where to find the canonical list of FRs to check against.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-04-final-validation.md` around lines 48 - 58, Update the "FR Coverage Validation" section in step-04-final-validation.md to explicitly state where and how to access the canonical Requirements Inventory: name the source (e.g., "Requirements Inventory in the PRD under Appendix A" or "requirements.yaml at the repo root"), describe its format (e.g., numbered list, YAML with keys id/description), and give the access method (e.g., "open PRD file at PRD.md", "view requirements.yaml in the repo", or "use the Requirements tab in the project board"); ensure the instruction that currently reads "Go through each FR from the Requirements Inventory" references this named source and format so the agent can locate and iterate the FR entries during validation.
129-131:⚠️ Potential issue | 🟠 MajorConflicting post-completion instructions.
Lines 129 and 131 give contradictory guidance:
- Line 129: "Invoke the
bmad-helpskill" (delegate to help)- Line 131: "offer to answer any questions about the Epics and Stories" (agent handles questions)
Should the agent answer questions itself or delegate to bmad-help? Both? If both, in what order?
Additionally, line 131's trigger "Upon Completion of task output" is ambiguous. What is "task output" — the epics.md save? The help invocation? The validation completion message?
Clarify the intended flow and consolidate these instructions into a clear sequence.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-04-final-validation.md` around lines 129 - 131, The post-completion instructions conflict: "Invoke the `bmad-help` skill" and "Upon Completion of task output: offer to answer any questions about the Epics and Stories"; clarify and consolidate into a single flow by specifying whether the agent should (a) call the bmad-help skill first and only delegate unanswered queries, (b) answer questions itself and call bmad-help as fallback, or (c) always present both options to the user. Update the step-04-final-validation.md text to define the trigger for "task output" (e.g., after saving epics.md and stories.md or after validation completes), state the exact order (e.g., "After saving epics.md and completing validation, present the validated summary, then ask if the user has questions; if yes, attempt to answer locally and if unable, invoke bmad-help"), and replace the two conflicting lines ("Invoke the `bmad-help` skill" and "Upon Completion of task output: offer to answer any questions about the Epics and Stories") with that single clear sequence.
85-93:⚠️ Potential issue | 🔴 CriticalMissing File Churn Check validation.
Epic Structure Validation is incomplete. Based on learnings from PR
#1826, this section should include a File Churn Check that validates whether epics with partial file overlap have been appropriately consolidated or explicitly separated with rationale. The current checks (user value, dependencies, foundation setup) don't address file overlap or churn concerns at all.The agent should assess whether epics touching the same files/components have been structured to minimize churn and whether consolidation decisions were made appropriately.
Based on learnings from PR
#1826: "Validation checks such as the File Churn Check (Epic Structure Validation) do not require formal serialized data structures... because the agent can assess file overlap and recall consolidation decisions from its own session context."🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-04-final-validation.md` around lines 85 - 93, Add a "File Churn Check" subsection under the existing "4. Epic Structure Validation" header that instructs the agent to detect epics that touch the same files/components and verify they were either consolidated or explicitly separated with a rationale; reference the section title "Epic Structure Validation" and the new check name "File Churn Check", describe the validation steps (identify partial file overlap across epics, confirm consolidation or explicit separation with justification, flag unaddressed overlaps), and note that this check may rely on the agent's session context rather than a serialized data structure when assessing consolidation decisions.
59-73:⚠️ Potential issue | 🟠 MajorArchitecture validation has contradictory guidance.
Lines 63-65 mandate that if a starter template is specified, "Epic 1 Story 1 must be 'Set up initial project from starter template'". But lines 69-72 say tables should be "created as part of the first story that needs them" and that "Epic 1 creates all tables upfront" is WRONG.
How do these rules integrate when:
- The starter template includes database schema setup?
- The first story needing tables is Epic 1 Story 1 (the template setup)?
- The template setup requires entities/tables to run?
The validation doesn't explain how to reconcile "template setup as Epic 1 Story 1" with "don't create tables upfront". This could lead to inconsistent agent interpretations.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-04-final-validation.md` around lines 59 - 73, The Architecture Implementation Validation is contradictory about starter templates vs. not creating tables upfront; update the guidance so that "Check for Starter Template Setup" and "Database/Entity Creation Validation" are reconciled: if a starter template is specified and it includes required runtime schema, allow Epic 1 Story 1 ("Set up initial project from starter template") to create only the minimal tables/entities that the template requires to run, but explicitly forbid creating any additional or optional domain tables up front; require the story to document which tables are created by the template (mark them as "template-required") and require subsequent stories to create/modify all other entities as-needed. Ensure the text under the headings "Check for Starter Template Setup" and "Database/Entity Creation Validation" and the example reference to "Epic 1 Story 1" reflect this rule.
46-113:⚠️ Potential issue | 🔴 CriticalNo failure path for validation checks.
Sections 1-5 describe critical validation checks (FR coverage, architecture, story quality, epic structure, dependencies), but nowhere in the file is there guidance on what to do when a validation fails. Line 116 only handles "If all validations pass" with no else clause.
What should the agent do when it detects:
- Missing FR coverage?
- Forward dependencies in stories?
- Epic independence violations?
- Incomplete acceptance criteria?
Without a failure path (HALT + remediation guidance, or loop back to previous steps, or user consultation), these validations are aspirational checklists that can't enforce quality.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-04-final-validation.md` around lines 46 - 113, The validation doc lists checks (sections "1. FR Coverage Validation", "2. Architecture Implementation Validation", "3. Story Quality Validation", "4. Epic Structure Validation", "5. Dependency Validation (CRITICAL)") but lacks explicit failure paths; update the file to add a single standardized failure procedure: when any check fails (e.g., missing FR coverage, forward dependencies, epic independence violations, incomplete acceptance criteria) the agent must HALT progression, mark the offending epic/story with a failure tag and a concise failure reason, create a remediation task that either (a) auto-suggests concrete fixes (e.g., add missing FRs to stories, split/fix dependencies, expand acceptance criteria) or (b) routes the item back to the "Create Epics and Stories" step for author revision, and notify the user with the list of failures and required actions; reference the validation sections above and implement this as the "else" branch to the existing "If all validations pass" clause.
🧹 Nitpick comments (4)
src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-04-final-validation.md (4)
118-120: Save operation semantics are unclear.Line 120 says "Save the final epics.md" but doesn't clarify:
- Is this the first save, or an update to a previously saved file?
- What changed since the last save (if any)?
- Should metadata be updated (e.g., validation_status: complete, validated_at: timestamp)?
- Where is the epics.md path defined (not in this step file's visible context)?
The instruction suggests finalization but without specifying what makes this save different from any previous saves, the agent might just re-write the same content. Consider adding explicit finalization semantics or metadata updates.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-04-final-validation.md` around lines 118 - 120, Clarify and enforce explicit finalization semantics for the "Save the final epics.md" step: specify whether the operation is a create or update of epics.md, ensure the agent records what changed since the previous save, and update file metadata (e.g., validation_status: "complete", validated_at: <ISO timestamp>, validated_by: <agent/id>) before writing; also reference the canonical file path/config where epics.md lives and perform an atomic write (write to temp then rename) so the step "Save the final epics.md" unambiguously marks finalization and persists the validation metadata.
94-113: Dependency Validation lacks executable procedure.Lines 96-113 ask complex questions like "Can Epic 2 function without Epic 3 being implemented?" and "Can Story N.2 be completed using only Story N.1 output?" but don't specify the verification procedure.
How should the agent verify these? Should it:
- Trace through all story acceptance criteria looking for cross-references?
- Build a dependency graph of inputs/outputs?
- Check for mentions of future story features in current stories?
- Review technical implementation details?
Without procedural guidance, different validation runs might apply different methods, leading to inconsistent results. Add a verification checklist or reasoning framework for each dependency question.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-04-final-validation.md` around lines 94 - 113, The "Dependency Validation (CRITICAL)" section (Epic Independence Check and Within-Epic Story Dependency Check) lacks a reproducible procedure; add a concise verification checklist the agent must follow: 1) Trace each epic/story acceptance criteria and list explicit inputs/outputs; 2) Build a dependency graph mapping outputs->consumers and flag any edges that point to later epics/stories; 3) Scan acceptance criteria text for explicit "future" references or unmet feature mentions and mark as dependency violations; 4) For any flagged item, attempt a minimal mock/flow reasoning step (using only listed outputs) to confirm if the downstream work is possible; 5) Only escalate to implementation-level review when the checklist shows ambiguous dependencies—document results per epic/story. Reference the section headings "Epic Independence Check" and "Within-Epic Story Dependency Check" when inserting the checklist.
85-93: Epic Structure criteria are too vague.Lines 91-92 use subjective terms without clear definitions:
- "Foundation stories only setup what's needed" — needed by the next story? The whole epic? All epics?
- "No big upfront technical work" — how is "big" determined? By time, scope, lines of code, dependencies?
Without reasoning guidance, the agent can't consistently apply these checks. While hard numeric thresholds should be avoided (per learnings), the criteria need enough context for the agent to reason. For example:
- "Setup needed by the next 2-3 stories in the epic, not for all future epics"
- "Technical work proportional to immediate story value delivery, not comprehensive future-proofing"
This would preserve flexibility while enabling consistent validation.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-04-final-validation.md` around lines 85 - 93, The "4. Epic Structure Validation" section uses vague terms; update that block (the "Epic Structure Validation" heading and the two bullets mentioning "Foundation stories only setup what's needed" and "No big upfront technical work") to define what "what's needed" means (e.g., setup required to unblock the next 2–3 stories in the same epic and not for unrelated future epics) and clarify "big" by framing it as "technical work proportional to immediate user-value delivery" with qualitative guidance (e.g., prefer incremental, shippable setup that enables the next stories rather than comprehensive future-proofing; escalate only when work exceeds X sprint-sized effort or introduces cross-epic dependencies), so the agent can apply consistent reasoning; keep the wording concise and provide one short example for each bullet to illustrate the threshold.
125-125: HALT message lacks input specificity.Line 125 says "HALT — wait for user input before proceeding" but doesn't specify what valid inputs are. Line 123 presents "[C] Complete Workflow" but the HALT message doesn't reference it.
The user might be confused about:
- Is only "C" valid?
- Can I ask questions first?
- Can I request specific validation details?
- What happens if I type something else?
Make the HALT more specific: "HALT — waiting for you to select [C] to complete the workflow, or ask any questions about the validation results."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-04-final-validation.md` at line 125, Replace the vague HALT line "HALT — wait for user input before proceeding" with a specific prompt tied to the existing option "[C] Complete Workflow": update the text to read something like "HALT — waiting for you to select [C] to complete the workflow, or ask any questions about the validation results." Ensure the change targets the line that currently contains "HALT — wait for user input before proceeding" and clearly references the "[C] Complete Workflow" option so users know valid actions.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Outside diff comments:
In
`@src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-04-final-validation.md`:
- Around line 116-123: The final validation step currently prints "All
validations complete!" without any results; update the Step 04 finalization flow
in step-04-final-validation.md to insert a concise validation summary before the
"Present Final Menu" section that lists: the number of FRs validated for
coverage (FR Coverage), the number of stories checked for quality (Story
Quality), dependency validation outcomes (Dependencies) including any unresolved
items, architecture compliance findings (Architecture) and any warnings/notes
(Epic Structure and Complete and Save); ensure the summary references those six
validation sections by name and presents numeric counts and short status lines
so the user can verify what was executed before the completion menu is shown.
- Around line 48-58: Update the "FR Coverage Validation" section in
step-04-final-validation.md to explicitly state where and how to access the
canonical Requirements Inventory: name the source (e.g., "Requirements Inventory
in the PRD under Appendix A" or "requirements.yaml at the repo root"), describe
its format (e.g., numbered list, YAML with keys id/description), and give the
access method (e.g., "open PRD file at PRD.md", "view requirements.yaml in the
repo", or "use the Requirements tab in the project board"); ensure the
instruction that currently reads "Go through each FR from the Requirements
Inventory" references this named source and format so the agent can locate and
iterate the FR entries during validation.
- Around line 129-131: The post-completion instructions conflict: "Invoke the
`bmad-help` skill" and "Upon Completion of task output: offer to answer any
questions about the Epics and Stories"; clarify and consolidate into a single
flow by specifying whether the agent should (a) call the bmad-help skill first
and only delegate unanswered queries, (b) answer questions itself and call
bmad-help as fallback, or (c) always present both options to the user. Update
the step-04-final-validation.md text to define the trigger for "task output"
(e.g., after saving epics.md and stories.md or after validation completes),
state the exact order (e.g., "After saving epics.md and completing validation,
present the validated summary, then ask if the user has questions; if yes,
attempt to answer locally and if unable, invoke bmad-help"), and replace the two
conflicting lines ("Invoke the `bmad-help` skill" and "Upon Completion of task
output: offer to answer any questions about the Epics and Stories") with that
single clear sequence.
- Around line 85-93: Add a "File Churn Check" subsection under the existing "4.
Epic Structure Validation" header that instructs the agent to detect epics that
touch the same files/components and verify they were either consolidated or
explicitly separated with a rationale; reference the section title "Epic
Structure Validation" and the new check name "File Churn Check", describe the
validation steps (identify partial file overlap across epics, confirm
consolidation or explicit separation with justification, flag unaddressed
overlaps), and note that this check may rely on the agent's session context
rather than a serialized data structure when assessing consolidation decisions.
- Around line 59-73: The Architecture Implementation Validation is contradictory
about starter templates vs. not creating tables upfront; update the guidance so
that "Check for Starter Template Setup" and "Database/Entity Creation
Validation" are reconciled: if a starter template is specified and it includes
required runtime schema, allow Epic 1 Story 1 ("Set up initial project from
starter template") to create only the minimal tables/entities that the template
requires to run, but explicitly forbid creating any additional or optional
domain tables up front; require the story to document which tables are created
by the template (mark them as "template-required") and require subsequent
stories to create/modify all other entities as-needed. Ensure the text under the
headings "Check for Starter Template Setup" and "Database/Entity Creation
Validation" and the example reference to "Epic 1 Story 1" reflect this rule.
- Around line 46-113: The validation doc lists checks (sections "1. FR Coverage
Validation", "2. Architecture Implementation Validation", "3. Story Quality
Validation", "4. Epic Structure Validation", "5. Dependency Validation
(CRITICAL)") but lacks explicit failure paths; update the file to add a single
standardized failure procedure: when any check fails (e.g., missing FR coverage,
forward dependencies, epic independence violations, incomplete acceptance
criteria) the agent must HALT progression, mark the offending epic/story with a
failure tag and a concise failure reason, create a remediation task that either
(a) auto-suggests concrete fixes (e.g., add missing FRs to stories, split/fix
dependencies, expand acceptance criteria) or (b) routes the item back to the
"Create Epics and Stories" step for author revision, and notify the user with
the list of failures and required actions; reference the validation sections
above and implement this as the "else" branch to the existing "If all
validations pass" clause.
---
Nitpick comments:
In
`@src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-04-final-validation.md`:
- Around line 118-120: Clarify and enforce explicit finalization semantics for
the "Save the final epics.md" step: specify whether the operation is a create or
update of epics.md, ensure the agent records what changed since the previous
save, and update file metadata (e.g., validation_status: "complete",
validated_at: <ISO timestamp>, validated_by: <agent/id>) before writing; also
reference the canonical file path/config where epics.md lives and perform an
atomic write (write to temp then rename) so the step "Save the final epics.md"
unambiguously marks finalization and persists the validation metadata.
- Around line 94-113: The "Dependency Validation (CRITICAL)" section (Epic
Independence Check and Within-Epic Story Dependency Check) lacks a reproducible
procedure; add a concise verification checklist the agent must follow: 1) Trace
each epic/story acceptance criteria and list explicit inputs/outputs; 2) Build a
dependency graph mapping outputs->consumers and flag any edges that point to
later epics/stories; 3) Scan acceptance criteria text for explicit "future"
references or unmet feature mentions and mark as dependency violations; 4) For
any flagged item, attempt a minimal mock/flow reasoning step (using only listed
outputs) to confirm if the downstream work is possible; 5) Only escalate to
implementation-level review when the checklist shows ambiguous
dependencies—document results per epic/story. Reference the section headings
"Epic Independence Check" and "Within-Epic Story Dependency Check" when
inserting the checklist.
- Around line 85-93: The "4. Epic Structure Validation" section uses vague
terms; update that block (the "Epic Structure Validation" heading and the two
bullets mentioning "Foundation stories only setup what's needed" and "No big
upfront technical work") to define what "what's needed" means (e.g., setup
required to unblock the next 2–3 stories in the same epic and not for unrelated
future epics) and clarify "big" by framing it as "technical work proportional to
immediate user-value delivery" with qualitative guidance (e.g., prefer
incremental, shippable setup that enables the next stories rather than
comprehensive future-proofing; escalate only when work exceeds X sprint-sized
effort or introduces cross-epic dependencies), so the agent can apply consistent
reasoning; keep the wording concise and provide one short example for each
bullet to illustrate the threshold.
- Line 125: Replace the vague HALT line "HALT — wait for user input before
proceeding" with a specific prompt tied to the existing option "[C] Complete
Workflow": update the text to read something like "HALT — waiting for you to
select [C] to complete the workflow, or ask any questions about the validation
results." Ensure the change targets the line that currently contains "HALT —
wait for user input before proceeding" and clearly references the "[C] Complete
Workflow" option so users know valid actions.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 06f4ea0b-e13b-4017-920e-6b1c556c2d31
📒 Files selected for processing (4)
src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-01-validate-prerequisites.mdsrc/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-02-design-epics.mdsrc/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-03-create-stories.mdsrc/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-04-final-validation.md
💤 Files with no reviewable changes (3)
- src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-02-design-epics.md
- src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-03-create-stories.md
- src/bmm/workflows/3-solutioning/bmad-create-epics-and-stories/steps/step-01-validate-prerequisites.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
name/descriptionfrom all 4 step file frontmatters (STEP-06)Test plan
🤖 Generated with Claude Code