fix: add File List and Change Log structure to story template#1902
Open
nikolasdehor wants to merge 1 commit intobmad-code-org:mainfrom
Open
fix: add File List and Change Log structure to story template#1902nikolasdehor wants to merge 1 commit intobmad-code-org:mainfrom
nikolasdehor wants to merge 1 commit intobmad-code-org:mainfrom
Conversation
The create-story template ended with an empty File List section, providing no guidance on format. The dev-story workflow expects structured File List entries (new/modified/deleted with paths) and a Change Log section, but the template included neither. Adds table format with action/path columns for File List and date/summary columns for Change Log, matching the dev-story workflow's expectations. Fixes bmad-code-org#1789
📝 WalkthroughWalkthroughThe change adds template scaffolding to the story creation template with structured sections for File List and Change Log. Both sections include Markdown table templates and HTML comments for populating rows during story implementation execution. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~2 minutes Suggested reviewers
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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.
Actionable comments posted: 7
🧹 Nitpick comments (3)
src/bmm/workflows/4-implementation/create-story/template.md (3)
63-65:Summarycollapses “what changed” and “why” into one free-form field.Your instruction says to capture both, but the schema only gives one column. Split this into something like
ChangeandReason/Taskso entries stay consistent and audit-friendly.Possible schema fix
-| Date | Summary | -|------|---------| -<!-- | YYYY-MM-DD | Initial implementation of story tasks | --> +| Date | Change | Reason / Task | +|------|--------|---------------| +<!-- | YYYY-MM-DD | Initial implementation of story tasks | Implement AC-1 and AC-2 | -->🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/4-implementation/create-story/template.md` around lines 63 - 65, The "Summary" column in the change log table conflates what changed and why; update the table header row in template.md to use two explicit columns (for example "Change" and "Reason" or "Task" and "Why") and update any corresponding example/commented row (the commented `YYYY-MM-DD` line) to populate both columns so entries remain consistent and audit-friendly; ensure any documentation text in create-story/template.md that references "Summary" is also updated to use the new column names.
53-57: The allowedActionvalues are undefined.If one agent writes
Updatedand another writesModified, any downstream validation becomes brittle. Define the permitted values explicitly in the comment so this stays machine-checkable.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/4-implementation/create-story/template.md` around lines 53 - 57, The table in template.md leaves the allowed Action values implicit, which makes downstream validation brittle; update the template (the table header or an adjacent comment) to explicitly enumerate the permitted Action enum values (e.g., Added, Modified, Deleted, Renamed, Updated) and normalize on a single canonical term for similar meanings (e.g., choose Modified instead of Updated) so agents produce consistent values; modify the placeholder commented rows (the lines containing src/example/...) and add a short machine-readable note (CSV/JSON schema or a parenthetical list) listing the exact permitted tokens so validators can rely on those identifiers.
63-65: The log ordering rule is missing.Right now it is unclear whether entries should be appended, replaced, oldest-first, or newest-first. That ambiguity makes the log unreliable during iterative story work. Add one explicit rule for ordering and append-only behavior.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/4-implementation/create-story/template.md` around lines 63 - 65, The template's activity log table (the header row "| Date | Summary |" and the commented example "<!-- | YYYY-MM-DD | Initial implementation of story tasks | -->") lacks an explicit ordering rule; update the template to state a single rule such as "Append-only; add new entries at the top (newest-first)" and include that line directly above or below the table so every story uses the same behavior; ensure the comment/example row is updated to reflect the append-only newest-first convention.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/bmm/workflows/4-implementation/create-story/template.md`:
- Around line 61-65: The change log table in the create-story template currently
only contains commented guidance so the rendered Markdown shows an empty table;
replace the commented guidance with a visible placeholder row (e.g., add a row
like "| YYYY-MM-DD | Add a short summary of changes |") under the header and
remove or move the HTML comment so maintainers see a cue; update the template
block that starts with the table header and the commented line to include the
visible placeholder row to guide human editors.
- Around line 53-57: The change log table uses a single "File Path" column which
cannot represent renames/moves; update the template row and header (the table
starting with "| Action | File Path |") to include either separate "Old Path"
and "New Path" columns or introduce a distinct "rename" action pattern that
records both paths (e.g., change the header and sample commented rows to show
"Old Path" and "New Path" or add an explicit "Renamed | old -> new" row); ensure
examples in the file (the commented sample rows) reflect the new schema and that
any tooling that consumes this template can parse the new columns or pattern.
- Around line 51-57: The table in template.md currently reads "<!-- Populated
during dev-story execution. List ALL new, modified, or deleted files (paths
relative to repo root). -->" which is underspecified; update that comment in
src/bmm/workflows/4-implementation/create-story/template.md to require the
file-change table be refreshed after each task and once more immediately before
final story completion, and also adjust any dev-story tooling/workflow that
populates the table (the dev-story execution step) so it triggers an update
after every task and a final refresh prior to completion; ensure the comment
explicitly states the cadence ("refresh after each task and again before final
completion") so the automation and reviewers follow the required timing.
- Around line 51-57: The template's guidance is hidden because the instructions
are inside HTML comments above the generated table; update the template.md (the
HTML comment block and the table starting with "<!-- Populated during dev-story
execution..." and the markdown table header "| Action | File Path |") to include
at least one visible instruction or placeholder row (e.g., a human-facing note
or a starter row) above the table so rendered stories show guidance to users.
- Around line 51-57: The template line "Populated during dev-story execution.
List ALL new, modified, or deleted files (paths relative to repo root)." does
not require the workflow to use git as the authoritative source; change that
text to explicitly instruct the workflow to run git status --porcelain and git
diff --name-only (or equivalent porcelain checks) during dev-story execution,
use those outputs as the ground truth to populate/reconcile the table, and emit
a warning or fail the run if the agent-populated list does not match git’s
results so the file list cannot drift from the repo.
- Around line 51-57: Update the template text in create-story/template.md to
remove ambiguity: replace the current "List ALL new, modified, or deleted files"
line with an explicit rule that repo-root side effects (e.g., lockfiles like
pnpm-lock.yaml) must be listed, while workflow artifact directories (_bmad/ and
_bmad-output/) and their contents must be excluded from the list unless they
were intentionally committed; reference issue `#1789` for context and include an
example clarifying "Included: pnpm-lock.yaml" and "Excluded: _bmad/,
_bmad-output/".
- Around line 55-57: The examples in the commit-file table only show src/ paths
and teach the wrong mental model; update the template in
create-story/template.md by adding at least one repo-root example (e.g., a row
like <!-- | Added | pnpm-lock.yaml | -->) to the commented example table so it
demonstrates non-source files belong in the file list alongside the existing
<!-- | Added | src/example/new-file.ts | -->, <!-- | Modified |
src/example/existing-file.ts | --> and <!-- | Deleted |
src/example/removed-file.ts | --> entries.
---
Nitpick comments:
In `@src/bmm/workflows/4-implementation/create-story/template.md`:
- Around line 63-65: The "Summary" column in the change log table conflates what
changed and why; update the table header row in template.md to use two explicit
columns (for example "Change" and "Reason" or "Task" and "Why") and update any
corresponding example/commented row (the commented `YYYY-MM-DD` line) to
populate both columns so entries remain consistent and audit-friendly; ensure
any documentation text in create-story/template.md that references "Summary" is
also updated to use the new column names.
- Around line 53-57: The table in template.md leaves the allowed Action values
implicit, which makes downstream validation brittle; update the template (the
table header or an adjacent comment) to explicitly enumerate the permitted
Action enum values (e.g., Added, Modified, Deleted, Renamed, Updated) and
normalize on a single canonical term for similar meanings (e.g., choose Modified
instead of Updated) so agents produce consistent values; modify the placeholder
commented rows (the lines containing src/example/...) and add a short
machine-readable note (CSV/JSON schema or a parenthetical list) listing the
exact permitted tokens so validators can rely on those identifiers.
- Around line 63-65: The template's activity log table (the header row "| Date |
Summary |" and the commented example "<!-- | YYYY-MM-DD | Initial implementation
of story tasks | -->") lacks an explicit ordering rule; update the template to
state a single rule such as "Append-only; add new entries at the top
(newest-first)" and include that line directly above or below the table so every
story uses the same behavior; ensure the comment/example row is updated to
reflect the append-only newest-first convention.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 1627c626-1f7b-4b4f-a435-6c43289e2b77
📒 Files selected for processing (1)
src/bmm/workflows/4-implementation/create-story/template.md
Comment on lines
+51
to
+57
| <!-- Populated during dev-story execution. List ALL new, modified, or deleted files (paths relative to repo root). --> | ||
|
|
||
| | Action | File Path | | ||
| |--------|-----------| | ||
| <!-- | Added | src/example/new-file.ts | --> | ||
| <!-- | Modified | src/example/existing-file.ts | --> | ||
| <!-- | Deleted | src/example/removed-file.ts | --> |
There was a problem hiding this comment.
The update cadence is underspecified.
“During dev-story execution” is too vague for the failure mode in #1789. The workflow needs this refreshed after each task and again before final completion; otherwise the table can still drift by the end of the story.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/bmm/workflows/4-implementation/create-story/template.md` around lines 51
- 57, The table in template.md currently reads "<!-- Populated during dev-story
execution. List ALL new, modified, or deleted files (paths relative to repo
root). -->" which is underspecified; update that comment in
src/bmm/workflows/4-implementation/create-story/template.md to require the
file-change table be refreshed after each task and once more immediately before
final story completion, and also adjust any dev-story tooling/workflow that
populates the table (the dev-story execution step) so it triggers an update
after every task and a final refresh prior to completion; ensure the comment
explicitly states the cadence ("refresh after each task and again before final
completion") so the automation and reviewers follow the required timing.
Hidden instructions disappear in rendered stories.
Because the guidance and examples are inside HTML comments, a GitHub-rendered story shows only an empty table. That guts the human-facing guidance this change is supposed to add. Keep at least one visible instruction line or placeholder row above the table.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/bmm/workflows/4-implementation/create-story/template.md` around lines 51
- 57, The template's guidance is hidden because the instructions are inside HTML
comments above the generated table; update the template.md (the HTML comment
block and the table starting with "<!-- Populated during dev-story execution..."
and the markdown table header "| Action | File Path |") to include at least one
visible instruction or placeholder row (e.g., a human-facing note or a starter
row) above the table so rendered stories show guidance to users.
The template still does not tell the workflow to use git as ground truth.
The linked issue was about agent-maintained file lists drifting from actual repo changes. This note only says “Populated during dev-story execution”, so it still leaves completeness to agent judgment instead of reconciling against git status --porcelain / git diff --name-only.
Suggested template wording
-<!-- Populated during dev-story execution. List ALL new, modified, or deleted files (paths relative to repo root). -->
+<!-- Populated during dev-story execution. Reconcile this table against git output
+ (for example: git status --porcelain and git diff --name-only, including staged changes)
+ so the file list reflects repo changes rather than agent memory. Paths must be relative to repo root. -->🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/bmm/workflows/4-implementation/create-story/template.md` around lines 51
- 57, The template line "Populated during dev-story execution. List ALL new,
modified, or deleted files (paths relative to repo root)." does not require the
workflow to use git as the authoritative source; change that text to explicitly
instruct the workflow to run git status --porcelain and git diff --name-only (or
equivalent porcelain checks) during dev-story execution, use those outputs as
the ground truth to populate/reconcile the table, and emit a warning or fail the
run if the agent-populated list does not match git’s results so the file list
cannot drift from the repo.
The inclusion/exclusion rule is still ambiguous for workflow artifacts.
“List ALL new, modified, or deleted files” conflicts with the intended behavior from #1789: repo-root side effects like pnpm-lock.yaml should be captured, but _bmad/ and _bmad-output/ workflow artifacts should not be auto-added. Spell that out here or authors will keep over/under-reporting files.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/bmm/workflows/4-implementation/create-story/template.md` around lines 51
- 57, Update the template text in create-story/template.md to remove ambiguity:
replace the current "List ALL new, modified, or deleted files" line with an
explicit rule that repo-root side effects (e.g., lockfiles like pnpm-lock.yaml)
must be listed, while workflow artifact directories (_bmad/ and _bmad-output/)
and their contents must be excluded from the list unless they were intentionally
committed; reference issue `#1789` for context and include an example clarifying
"Included: pnpm-lock.yaml" and "Excluded: _bmad/, _bmad-output/".
Comment on lines
+53
to
+57
| | Action | File Path | | ||
| |--------|-----------| | ||
| <!-- | Added | src/example/new-file.ts | --> | ||
| <!-- | Modified | src/example/existing-file.ts | --> | ||
| <!-- | Deleted | src/example/removed-file.ts | --> |
There was a problem hiding this comment.
This table cannot represent renames or moves.
A single File Path column loses either the old path or the new path for rename/move cases. That makes the record ambiguous and hard to reconcile with git history. Add Old Path / New Path, or at minimum a dedicated rename action pattern.
Possible schema fix
-| Action | File Path |
-|--------|-----------|
-<!-- | Added | src/example/new-file.ts | -->
-<!-- | Modified | src/example/existing-file.ts | -->
-<!-- | Deleted | src/example/removed-file.ts | -->
+| Action | Old Path | New Path |
+|--------|----------|----------|
+<!-- | Added | | src/example/new-file.ts | -->
+<!-- | Modified | src/example/existing-file.ts | src/example/existing-file.ts | -->
+<!-- | Deleted | src/example/removed-file.ts | | -->
+<!-- | Renamed | src/example/old-name.ts | src/example/new-name.ts | -->📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| | Action | File Path | | |
| |--------|-----------| | |
| <!-- | Added | src/example/new-file.ts | --> | |
| <!-- | Modified | src/example/existing-file.ts | --> | |
| <!-- | Deleted | src/example/removed-file.ts | --> | |
| | Action | Old Path | New Path | | |
| |--------|----------|----------| | |
| <!-- | Added | | src/example/new-file.ts | --> | |
| <!-- | Modified | src/example/existing-file.ts | src/example/existing-file.ts | --> | |
| <!-- | Deleted | src/example/removed-file.ts | | --> | |
| <!-- | Renamed | src/example/old-name.ts | src/example/new-name.ts | --> |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/bmm/workflows/4-implementation/create-story/template.md` around lines 53
- 57, The change log table uses a single "File Path" column which cannot
represent renames/moves; update the template row and header (the table starting
with "| Action | File Path |") to include either separate "Old Path" and "New
Path" columns or introduce a distinct "rename" action pattern that records both
paths (e.g., change the header and sample commented rows to show "Old Path" and
"New Path" or add an explicit "Renamed | old -> new" row); ensure examples in
the file (the commented sample rows) reflect the new schema and that any tooling
that consumes this template can parse the new columns or pattern.
Comment on lines
+55
to
+57
| <!-- | Added | src/example/new-file.ts | --> | ||
| <!-- | Modified | src/example/existing-file.ts | --> | ||
| <!-- | Deleted | src/example/removed-file.ts | --> |
There was a problem hiding this comment.
The examples reinforce the wrong mental model.
All examples live under src/, which is exactly how infra side-effect files get forgotten. Add at least one repo-root example such as pnpm-lock.yaml so the template teaches that non-source changes still belong in the file list.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/bmm/workflows/4-implementation/create-story/template.md` around lines 55
- 57, The examples in the commit-file table only show src/ paths and teach the
wrong mental model; update the template in create-story/template.md by adding at
least one repo-root example (e.g., a row like <!-- | Added | pnpm-lock.yaml |
-->) to the commented example table so it demonstrates non-source files belong
in the file list alongside the existing <!-- | Added | src/example/new-file.ts |
-->, <!-- | Modified | src/example/existing-file.ts | --> and <!-- | Deleted |
src/example/removed-file.ts | --> entries.
Comment on lines
+61
to
+65
| <!-- Populated during dev-story execution. Summarize what changed and why. --> | ||
|
|
||
| | Date | Summary | | ||
| |------|---------| | ||
| <!-- | YYYY-MM-DD | Initial implementation of story tasks | --> |
There was a problem hiding this comment.
The Change Log guidance is also invisible in rendered Markdown.
Rendered output becomes an empty table with no visible cue about what belongs here. If humans are expected to maintain this, keep a short visible note or placeholder row instead of hiding all guidance in comments.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/bmm/workflows/4-implementation/create-story/template.md` around lines 61
- 65, The change log table in the create-story template currently only contains
commented guidance so the rendered Markdown shows an empty table; replace the
commented guidance with a visible placeholder row (e.g., add a row like "|
YYYY-MM-DD | Add a short summary of changes |") under the header and remove or
move the HTML comment so maintainers see a cue; update the template block that
starts with the table header and the commented line to include the visible
placeholder row to guide human editors.
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.
What
Expand the
create-story/template.mdwith structured File List and Change Log sections.Why
The template ends with an empty
### File Listheader and no Change Log section. The dev-story workflow (steps 8-9) expects a structured File List with action/path entries and a Change Log with date/summary entries. Without guidance in the template, stories are systematically created with incomplete or missing file tracking.Fixes #1789
How
| Action | File Path |with comment examples (Added/Modified/Deleted)| Date | Summary |with comment exampleTesting