Skip to content

fix: add File List and Change Log structure to story template #1902

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

Closed
nikolasdehor wants to merge 1 commit into from
Closed

fix: add File List and Change Log structure to story template #1902

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
16 changes: 16 additions & 0 deletions src/bmm/workflows/4-implementation/create-story/template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,3 +47,19 @@ so that {{benefit}}.
### Completion Notes List

### File List

<!-- 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 | -->
Comment on lines +51 to +57
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 11, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟠 Major

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.

⚠️ Potential issue | 🟠 Major

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.

⚠️ Potential issue | 🟠 Major

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.

⚠️ Potential issue | 🟠 Major

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
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 11, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟠 Major

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
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 11, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

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.


### Change Log

<!-- Populated during dev-story execution. Summarize what changed and why. -->

| Date | Summary |
|------|---------|
<!-- | YYYY-MM-DD | Initial implementation of story tasks | -->
Comment on lines +61 to +65
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 11, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟠 Major

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.