Skip to content

fix(skill): clean up bmad-create-product-brief validation findings #1982

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

Merged
alexeyv merged 1 commit into from
Mar 14, 2026
Merged

fix(skill): clean up bmad-create-product-brief validation findings #1982

Show file tree
Hide file tree
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
4 changes: 2 additions & 2 deletions src/bmm/workflows/1-analysis/bmad-create-product-brief/product-brief.template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
---
stepsCompleted: []
inputDocuments: []
date: { system-date }
author: { user }
date: {{system-date}}
Copy link
Copy Markdown

@augmentcode augmentcode bot Mar 14, 2026

Choose a reason for hiding this comment

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

Most workflows/templates in this repo use {{date}} as the system-generated datetime variable; {{system-date}} may not be defined (and also diverges from the {{date}} used in the output filename patterns). If it’s not supported by the templating/installer, the product brief frontmatter date could remain unrendered.

Severity: medium

Fix This in Augment

🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.

author: {{user_name}}
Comment on lines +4 to +5
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 14, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

Document that the old syntax was broken, not just "cleaned up."

The PR description calls this "cleanup," but the old single-brace syntax { system-date } would never have been processed by the template engine (which uses /\{\{(\w+)\}\}/g). This is actually a bug fix that enables these fields to work for the first time. The PR description understates the impact.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In
`@src/bmm/workflows/1-analysis/bmad-create-product-brief/product-brief.template.md`
around lines 4 - 5, Update the PR description and changelog to state this change
is a bug fix (not just a "cleanup"): explain that the template engine uses the
regex /\{\{(\w+)\}\}/g and therefore the old single-brace tokens like "{
system-date }" were never matched, and that you converted them to the correct
double-brace tokens ("{{system-date}}", "{{user_name}}") so the fields now
render; mention the affected template (product-brief.template.md) and include an
explicit note that this enables those fields to work for the first time.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Search for where template variables are defined and what names are used
rg -n --type=js -C3 '\b(user_name|userName|user)\b.*=' tools/cli/

Repository: bmad-code-org/BMAD-METHOD

Length of output: 2961

🏁 Script executed:

#!/bin/bash
# Check the product-brief.template.md file
cat -n src/bmm/workflows/1-analysis/bmad-create-product-brief/product-brief.template.md | head -20

Repository: bmad-code-org/BMAD-METHOD

Length of output: 348

🏁 Script executed:

#!/bin/bash
# Search for template engine usage and how variables are provided to templates
rg -n "system-date|system_date" --type=js tools/cli/ | head -20

Repository: bmad-code-org/BMAD-METHOD

Length of output: 51

🏁 Script executed:

#!/bin/bash
# Look for template processing/rendering code
rg -n "template.*date|system.*date" --type=js -i tools/cli/ | head -20

Repository: bmad-code-org/BMAD-METHOD

Length of output: 51

🏁 Script executed:

#!/bin/bash
# Search for template rendering/processing code
rg -n "{{.*}}" --type=md | head -5

Repository: bmad-code-org/BMAD-METHOD

Length of output: 150

🏁 Script executed:

#!/bin/bash
# Search for where template files are processed
rg -n "template\.md|renderTemplate|processTemplate" --type=js -i | head -20

Repository: bmad-code-org/BMAD-METHOD

Length of output: 1162

🏁 Script executed:

#!/bin/bash
# Look for date variable assignment across the codebase
rg -n "system.*date|\.date\s*=" --type=js -i tools/cli/ -A 2 | head -30

Repository: bmad-code-org/BMAD-METHOD

Length of output: 51

🏁 Script executed:

#!/bin/bash
# Search for project_name variable to understand variable pattern
rg -n "project_name|projectName" --type=js tools/cli/ -C 2 | head -30

Repository: bmad-code-org/BMAD-METHOD

Length of output: 51

🏁 Script executed:

#!/bin/bash
# Read the template-engine.js file to understand how variables are processed
cat -n tools/cli/lib/agent/template-engine.js

Repository: bmad-code-org/BMAD-METHOD

Length of output: 5745

🏁 Script executed:

#!/bin/bash
# Search for where product-brief.template.md is referenced or processed
rg -n "product-brief" --type=js -C 3

Repository: bmad-code-org/BMAD-METHOD

Length of output: 51

🏁 Script executed:

#!/bin/bash
# Search for where date variables are set/created
rg -n "\"date\"|'date'|\.date\s*=" --type=js tools/cli/installers -A 2 | head -40

Repository: bmad-code-org/BMAD-METHOD

Length of output: 51

🏁 Script executed:

#!/bin/bash
# Search for workflow processing or where template files are loaded
rg -n "template\.md|\.template\.md" --type=js | head -20

Repository: bmad-code-org/BMAD-METHOD

Length of output: 357

🏁 Script executed:

#!/bin/bash
# Search for where system-date might be set - check all file types
rg -n "system.date|systemDate" --type=js --type=ts -i | head -20

Repository: bmad-code-org/BMAD-METHOD

Length of output: 51

🏁 Script executed:

#!/bin/bash
# Look at the workflow directory structure to understand how it's organized
find src/bmm/workflows -type f -name "*.js" -o -name "*.ts" -o -name "*.json" | head -20

Repository: bmad-code-org/BMAD-METHOD

Length of output: 150

🏁 Script executed:

#!/bin/bash
# Search for any reference to "date" in workflow config or similar
rg -n "date" src/bmm/workflows -i --type=json --type=yaml --type=md | head -30

Repository: bmad-code-org/BMAD-METHOD

Length of output: 5223

🏁 Script executed:

#!/bin/bash
# Look at the tech-spec-template.md to see the exact old syntax
cat -n src/bmm/workflows/bmad-quick-flow/bmad-quick-spec/tech-spec-template.md | head -20

Repository: bmad-code-org/BMAD-METHOD

Length of output: 458

🏁 Script executed:

#!/bin/bash
# Search for documentation about available template variables
rg -n "date.*system|system.*date|available.*variable|variable.*available" src/bmm/workflows -i -B 2 -A 2 | head -50

Repository: bmad-code-org/BMAD-METHOD

Length of output: 5318

🏁 Script executed:

#!/bin/bash
# Check if there are other product-brief templates or references
find src/bmm/workflows -name "*product*brief*" -o -name "*product*" | grep -i brief

Repository: bmad-code-org/BMAD-METHOD

Length of output: 204

Variable name mismatch: {{system-date}} should be {{date}}

The new template changed {date} to {{system-date}}, but all workflow documentation consistently defines the available variable as date, not system-date. The template engine will fail to replace {{system-date}} and leave a literal placeholder in the rendered output.

Correct to {{date}} to match the variable provided by the workflow system.

The variable {{user_name}} is correct and properly defined in the configuration system.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In
`@src/bmm/workflows/1-analysis/bmad-create-product-brief/product-brief.template.md`
around lines 4 - 5, The template uses the wrong date placeholder: replace the
incorrect {{system-date}} token with the workflow-provided {{date}} token in
product-brief.template.md so the template engine can interpolate the value;
leave {{user_name}} unchanged.

---

# Product Brief: {{project_name}}
Expand Down
15 changes: 4 additions & 11 deletions src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-01-init.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,6 @@
---
name: 'step-01-init'
description: 'Initialize the product brief workflow by detecting continuation state and setting up the document'

# File References
nextStepFile: './step-02-vision.md'
outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md'

# Template References
productBriefTemplate: '../product-brief.template.md'
---

# Step 1: Product Brief Initialization
Expand Down Expand Up @@ -88,7 +81,7 @@ load context documents using smart discovery. Documents can be in the following
- {planning_artifacts}/**
- {output_folder}/**
- {product_knowledge}/**
- docs/**
- {project-root}/docs/**
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 14, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟠 Major

Inconsistent path inlining: why keep {project-root} variable here?

Line 84 changes docs/** to {project-root}/docs/**, adding a variable prefix instead of inlining. But line 108 fully inlines {productBriefTemplate} to ../product-brief.template.md. The PR goal (PATH-04) is to "inline path variables as literal relative paths," yet {project-root} is retained as a variable. Either inline it to ../../../../../../ (brittle) or explain why this path gets special variable treatment while others don't.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-01-init.md`
at line 84, The change left the `{project-root}` variable in place while other
path variables like `{productBriefTemplate}` were inlined (per PATH-04); either
fully inline `{project-root}/docs/**` to the equivalent literal relative path
used elsewhere (for example the same number of ../ segments used to reach repo
root plus /docs/**) or remove the `{project-root}` prefix and use the
already-inlined form `docs/**` to match the PR's "inline path variables as
literal relative paths" rule; update the entry that currently reads
`{project-root}/docs/**` to one consistent approach and ensure it aligns with
the other inlined paths in the file.


Also - when searching - documents can be a single markdown file, or a folder with an index and multiple files. For Example, if searching for `*foo*.md` and not found, also search for a folder called *foo*/index.md (which indicates sharded content)

Expand All @@ -112,7 +105,7 @@ Try to discover the following:

**Document Setup:**

- Copy the template from `{productBriefTemplate}` to `{outputFile}`, and update the frontmatter fields
- Copy the template from `../product-brief.template.md` to `{outputFile}`, and update the frontmatter fields

#### C. Present Initialization Results

Expand Down Expand Up @@ -141,7 +134,7 @@ Display: "**Proceeding to product vision discovery...**"

#### Menu Handling Logic:

- After setup report is presented, without delay, read fully and follow: {nextStepFile}
- After setup report is presented, without delay, read fully and follow: ./step-02-vision.md

#### EXECUTION RULES:

Expand All @@ -150,7 +143,7 @@ Display: "**Proceeding to product vision discovery...**"

## CRITICAL STEP COMPLETION NOTE

ONLY WHEN [setup completion is achieved and frontmatter properly updated], will you then read fully and follow: `{nextStepFile}` to begin product vision discovery.
ONLY WHEN [setup completion is achieved and frontmatter properly updated], will you then read fully and follow: `./step-02-vision.md` to begin product vision discovery.

---

Expand Down
3 changes: 0 additions & 3 deletions src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-01b-continue.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,4 @@
---
name: 'step-01b-continue'
description: 'Resume the product brief workflow from where it was left off, ensuring smooth continuation'

# File References
outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md'
---
Expand Down
8 changes: 2 additions & 6 deletions src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-02-vision.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,5 @@
---
name: 'step-02-vision'
description: 'Discover and define the core product vision, problem statement, and unique value proposition'

# File References
nextStepFile: './step-03-users.md'
outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md'

# Task References
Expand Down Expand Up @@ -159,7 +155,7 @@ Prepare the following structure for document append:

- IF A: Read fully and follow: {advancedElicitationTask} with current vision content to dive deeper and refine
- IF P: Read fully and follow: {partyModeWorkflow} to bring different perspectives to positioning and differentiation
- IF C: Save content to {outputFile}, update frontmatter with stepsCompleted: [1, 2], then read fully and follow: {nextStepFile}
- IF C: Save content to {outputFile}, update frontmatter with stepsCompleted: [1, 2], then read fully and follow: ./step-03-users.md
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#7-present-menu-options)

#### EXECUTION RULES:
Expand All @@ -171,7 +167,7 @@ Prepare the following structure for document append:

## CRITICAL STEP COMPLETION NOTE

ONLY WHEN [C continue option] is selected and [vision content finalized and saved to document with frontmatter updated], will you then read fully and follow: `{nextStepFile}` to begin target user discovery.
ONLY WHEN [C continue option] is selected and [vision content finalized and saved to document with frontmatter updated], will you then read fully and follow: `./step-03-users.md` to begin target user discovery.

---

Expand Down
8 changes: 2 additions & 6 deletions src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-03-users.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,5 @@
---
name: 'step-03-users'
description: 'Define target users with rich personas and map their key interactions with the product'

# File References
nextStepFile: './step-04-metrics.md'
outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md'

# Task References
Expand Down Expand Up @@ -162,7 +158,7 @@ Prepare the following structure for document append:

- IF A: Read fully and follow: {advancedElicitationTask} with current user content to dive deeper into personas and journeys
- IF P: Read fully and follow: {partyModeWorkflow} to bring different perspectives to validate user understanding
- IF C: Save content to {outputFile}, update frontmatter with stepsCompleted: [1, 2, 3], then read fully and follow: {nextStepFile}
- IF C: Save content to {outputFile}, update frontmatter with stepsCompleted: [1, 2, 3], then read fully and follow: ./step-04-metrics.md
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#6-present-menu-options)

#### EXECUTION RULES:
Expand All @@ -174,7 +170,7 @@ Prepare the following structure for document append:

## CRITICAL STEP COMPLETION NOTE

ONLY WHEN [C continue option] is selected and [user personas finalized and saved to document with frontmatter updated], will you then read fully and follow: `{nextStepFile}` to begin success metrics definition.
ONLY WHEN [C continue option] is selected and [user personas finalized and saved to document with frontmatter updated], will you then read fully and follow: `./step-04-metrics.md` to begin success metrics definition.

---

Expand Down
8 changes: 2 additions & 6 deletions src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-04-metrics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,5 @@
---
name: 'step-04-metrics'
description: 'Define comprehensive success metrics that include user success, business objectives, and key performance indicators'

# File References
nextStepFile: './step-05-scope.md'
outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md'

# Task References
Expand Down Expand Up @@ -165,7 +161,7 @@ Prepare the following structure for document append:

- IF A: Read fully and follow: {advancedElicitationTask} with current metrics content to dive deeper into success metric insights
- IF P: Read fully and follow: {partyModeWorkflow} to bring different perspectives to validate comprehensive metrics
- IF C: Save content to {outputFile}, update frontmatter with stepsCompleted: [1, 2, 3, 4], then read fully and follow: {nextStepFile}
- IF C: Save content to {outputFile}, update frontmatter with stepsCompleted: [1, 2, 3, 4], then read fully and follow: ./step-05-scope.md
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#7-present-menu-options)

#### EXECUTION RULES:
Expand All @@ -177,7 +173,7 @@ Prepare the following structure for document append:

## CRITICAL STEP COMPLETION NOTE

ONLY WHEN [C continue option] is selected and [success metrics finalized and saved to document with frontmatter updated], will you then read fully and follow: `{nextStepFile}` to begin MVP scope definition.
ONLY WHEN [C continue option] is selected and [success metrics finalized and saved to document with frontmatter updated], will you then read fully and follow: `./step-05-scope.md` to begin MVP scope definition.

---

Expand Down
8 changes: 2 additions & 6 deletions src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-05-scope.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,5 @@
---
name: 'step-05-scope'
description: 'Define MVP scope with clear boundaries and outline future vision while managing scope creep'

# File References
nextStepFile: './step-06-complete.md'
outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md'

# Task References
Expand Down Expand Up @@ -179,7 +175,7 @@ Prepare the following structure for document append:

- IF A: Read fully and follow: {advancedElicitationTask} with current scope content to optimize scope definition
- IF P: Read fully and follow: {partyModeWorkflow} to bring different perspectives to validate MVP scope
- IF C: Save content to {outputFile}, update frontmatter with stepsCompleted: [1, 2, 3, 4, 5], then read fully and follow: {nextStepFile}
- IF C: Save content to {outputFile}, update frontmatter with stepsCompleted: [1, 2, 3, 4, 5], then read fully and follow: ./step-06-complete.md
- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#7-present-menu-options)

#### EXECUTION RULES:
Expand All @@ -191,7 +187,7 @@ Prepare the following structure for document append:

## CRITICAL STEP COMPLETION NOTE

ONLY WHEN [C continue option] is selected and [MVP scope finalized and saved to document with frontmatter updated], will you then read fully and follow: `{nextStepFile}` to complete the product brief workflow.
ONLY WHEN [C continue option] is selected and [MVP scope finalized and saved to document with frontmatter updated], will you then read fully and follow: `./step-06-complete.md` to complete the product brief workflow.

---

Expand Down
3 changes: 0 additions & 3 deletions src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-06-complete.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,4 @@
---
name: 'step-06-complete'
description: 'Complete the product brief workflow, update status files, and suggest next steps for the project'

# File References
outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md'
---
Expand Down
Loading