I created a story using /sm and *create-story
Then when I used *validate-story, /sm reporting missing sections in its own create-story template.
This is such a fundamental workflow in the bmad process I find it hard to believe no issues have been reported before me, so I am suspicion of LLM bullshit and making up a story that it will later deny. Having said that, its worth mentioning in case.
Is this an actual flaw in the bmad files, or am I missing something in my workflow process? I have a full set of prd, architecture, epics and this is my first story. Trying to avoid going through this every time I create a story, or implementing stories that are not ready or complete.
*validate-story
✦ Validation Report for Story: 1.1 - Implement Teacher Component
Based on my analysis of the story file against the validation checklist, I've identified several critical and major
issues that need to be addressed. Here's the summary:
Critical Issues Found
1. Missing Epic Citation: The story does not cite the epics.md file as a source, despite the epics file containing
the original requirements for this story.
2. Missing AC Source Statement: The story does not explicitly state the source of the acceptance criteria, which
should be referenced from the epics or architecture documents.
3. No Tech Spec Citation: The story should reference the tech-spec file if it exists, though in this case the tech
spec file for Epic 1 was not found.
Major Issues Found
1. Task-AC Mapping: Tasks in the story are not explicitly linked to specific acceptance criteria with notation like
(AC: #1).
2. Missing Dev Agent Record Sections: The Dev Agent Record section is incomplete and missing some required
subsections.
3. Missing Architecture Citations: While architecture guidance is provided, there are no explicit citations to the
architecture.md file.
Summary of Validation
- Story: 1-1-implement-teacher-component.md
- Outcome: FAIL (has critical issues that must be addressed)
- Critical Issues: 2
- Major Issues: 3
- Minor Issues: 2
Recommendations
I recommend addressing the critical issues in the following order:
1. Add citations to the epics.md file in the Dev Notes/References section
2. Explicitly state the source of the acceptance criteria (should reference epics.md)
3. Add explicit links from tasks to acceptance criteria numbers
4. Complete the Dev Agent Record with all required sections
5. Add specific citations to architecture.md in the Dev Notes
Would you like me to help improve the story by addressing these issues? I can assist in revising the story file to
meet the validation requirements.
Where is the problem?
The flaw is in the create-story workflow template itself, which is not generating stories that meet the validation requirements. The issue is systemic - the template is missing required elements that the validation checklist expects.
The specific flaws in the create-story workflow/template are:
1. Missing Automatic Citations: The template doesn't automatically include citations to source documents (epics.md,
architecture.md) that are required by the validation checklist.
2. Missing Task-AC Mapping: The template doesn't require or prompt for explicit links between tasks and acceptance
criteria numbers.
3. Incomplete Dev Agent Record: The template doesn't ensure all required Dev Agent Record sections are properly
initialized.
4. Missing Source Attribution: The template doesn't explicitly require stating the source of acceptance criteria.
5. Inadequate References Section: The template doesn't ensure comprehensive citations to all relevant architectural
and requirements documents.
The validation checklist expects stories to reference source documents like epics.md and architecture.md with
specific citation formats, but the create-story template isn't generating these. This is why every story created with
this template will fail validation in the same way.
To fix this permanently, the create-story workflow template needs to be updated to include these mandatory elements
that the validation checklist requires.
How should I fix this?
✦ Now that I've examined the template, instructions, and workflow engine, I can identify the specific flaw in the
create-story workflow template that's causing the validation failures:
The Primary Flaw: The template doesn't enforce the inclusion of source document citations in the "References"
section. The template has a placeholder:
1 ### References
2
3 - Cite all technical details with source paths and sections, e.g. [Source: docs/<file>.md#Section]
But there's no mechanism in the instructions to ensure that the actual source documents (epics.md, architecture.md,
etc.) are automatically referenced in this section. The instructions in step 6 mention to "Cite architecture/source
documents for any technical mandates" but don't enforce this in the References section.
Secondary Flaw: The template doesn't include the expected "Learnings from Previous Story" subsection even when it's
the first story in an epic. The instructions in step 7 do mention this, but the template doesn't include placeholder
content for it.
Tertiary Flaw: The template doesn't specify explicit task-AC mapping format in the instructions that would ensure
tasks reference specific acceptance criteria numbers.
The create-story workflow has the right intentions in the instructions but the template doesn't enforce the required
elements that the validation checklist expects, resulting in stories that consistently fail validation.
> so give me concise steps to fix this issue so future stories do validate
✦ Steps to Fix the Create-Story Template Issue
1. Update the Template File
Edit /Users/dave/Documents/Projects2026/babble/.bmad/bmm/workflows/4-implementation/create-story/template.md:
Replace the current "References" section with:
1 ### References
2
3 - [Source: docs/epics.md#Epic-{{epic_num}}]
4 - [Source: docs/architecture.md]
5 - Cite all technical details with source paths and sections, e.g. [Source: docs/<file>.md#Section]
2. Update the Template for Learnings Section
Replace the current "Dev Notes" section with:
1 ### Learnings from Previous Story
2 - {{learnings_from_previous_story}}
3
4 ### Project Structure Notes
5
6 - Alignment with unified project structure (paths, modules, naming)
7 - Detected conflicts or variances (with rationale)
8
9 ### References
10
11 - [Source: docs/epics.md#Epic-{{epic_num}}]
12 - [Source: docs/architecture.md]
13 - Cite all technical details with source paths and sections, e.g. [Source: docs/<file>.md#Section]
3. Modify Instructions to Ensure Task-AC Mapping
In the instructions.md file, update step 6 to require explicit AC references in tasks:
- Change the task template to require (AC: #) notation for each task
- Example: - [ ] Task 1 (AC: #1)
These changes will ensure that every story created will have the required citations and structure to pass validation.
I created a story using /sm and *create-story
Then when I used *validate-story, /sm reporting missing sections in its own create-story template.
This is such a fundamental workflow in the bmad process I find it hard to believe no issues have been reported before me, so I am suspicion of LLM bullshit and making up a story that it will later deny. Having said that, its worth mentioning in case.
Is this an actual flaw in the bmad files, or am I missing something in my workflow process? I have a full set of prd, architecture, epics and this is my first story. Trying to avoid going through this every time I create a story, or implementing stories that are not ready or complete.
*validate-story
Where is the problem?
How should I fix this?