docs: clarify BMad development paths - #2669
Conversation
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
There was a problem hiding this comment.
alexeyv has reached the 50-credit limit for trial accounts. To continue receiving code reviews, upgrade your plan.
📝 WalkthroughWalkthroughChangesWorkflow documentation
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ 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: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/explanation/retrospective.md`:
- Around line 67-69: Update the bmad-retrospective usage documentation to state
that no-input discovery first uses sprint-status.yaml and, when it is absent,
searches configured spec roots for spec-backed epics. Document that headless
discovery must receive an explicit epic number or spec folder when it cannot
safely select a single candidate, while preserving the existing default behavior
of stopping after the written report and verdict.
In `@docs/index.md`:
- Around line 8-9: Update the “Choose a development path” CTA link in the
documentation navigation to reference the existing
how-to/choose-a-development-path.md file, matching the path used elsewhere on
the page and the internal Markdown link requirement.
🪄 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 Plus
Run ID: 90dba84e-7590-4491-85ef-cf6c578d2bec
⛔ Files ignored due to path filters (1)
website/public/workflow-map-diagram.htmlis excluded by!website/**
📒 Files selected for processing (10)
docs/explanation/build.mddocs/explanation/retrospective.mddocs/how-to/choose-a-development-path.mddocs/how-to/get-answers-about-bmad.mddocs/how-to/quick-fixes.mddocs/index.mddocs/reference/build-auto.mddocs/reference/workflow-map.mddocs/tutorials/getting-deeper.mddocs/tutorials/getting-started.md
| Invoke `bmad-retrospective` with the epic number or spec folder. With no input, | ||
| it can find the completed epic from sprint status. By default, it stops at the | ||
| written report and verdict. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Document no-input discovery for spec-backed epics.
The current text describes no-input discovery through sprint-status.yaml only. When that file is absent, the skill searches the configured spec roots. It also requires an explicit folder when headless discovery cannot select one safely.
Add this behavior to prevent users from assuming that no-input discovery supports only sprint-tracked epics.
Proposed wording
- With no input, it can find the completed epic from sprint status. By default, it stops at the
+ With no input, it finds a completed epic from sprint status when available; otherwise, it searches
+ the configured spec roots. If multiple spec folders match, choose one explicitly. By default, it stops at the
written report and verdict.The supplied src/bmm-skills/ship/bmad-retrospective/SKILL.md contract includes spec-root discovery when sprint status is absent.
📝 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.
| Invoke `bmad-retrospective` with the epic number or spec folder. With no input, | |
| it can find the completed epic from sprint status. By default, it stops at the | |
| written report and verdict. | |
| Invoke `bmad-retrospective` with the epic number or spec folder. With no input, it finds a completed epic from sprint status when available; otherwise, it searches | |
| the configured spec roots. If multiple spec folders match, choose one explicitly. By default, it stops at the | |
| written report and verdict. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/explanation/retrospective.md` around lines 67 - 69, Update the
bmad-retrospective usage documentation to state that no-input discovery first
uses sprint-status.yaml and, when it is absent, searches configured spec roots
for spec-backed epics. Document that headless discovery must receive an explicit
epic number or spec folder when it cannot safely select a single candidate,
while preserving the existing default behavior of stopping after the written
report and verdict.
| - text: Choose a development path | ||
| link: ./how-to/choose-a-development-path/ |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Link the CTA to the existing Markdown file.
Line 9 uses ./how-to/choose-a-development-path/, but the referenced file is docs/how-to/choose-a-development-path.md. The same page already uses the .md path at Lines 28-29. Change the CTA link to the existing file path.
As per path instructions, internal Markdown links in docs/**/*.md must point to existing files.
Proposed fix
- link: ./how-to/choose-a-development-path/
+ link: ./how-to/choose-a-development-path.md📝 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.
| - text: Choose a development path | |
| link: ./how-to/choose-a-development-path/ | |
| - text: Choose a development path | |
| link: ./how-to/choose-a-development-path.md |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/index.md` around lines 8 - 9, Update the “Choose a development path” CTA
link in the documentation navigation to reference the existing
how-to/choose-a-development-path.md file, matching the path used elsewhere on
the page and the internal Markdown link requirement.
Source: Path instructions
b310e61 to
cf93acc
Compare
There was a problem hiding this comment.
alexeyv has reached the 50-credit limit for trial accounts. To continue receiving code reviews, upgrade your plan.
There was a problem hiding this comment.
alexeyv has reached the 50-credit limit for trial accounts. To continue receiving code reviews, upgrade your plan.
1 participant
What
Add a canonical guide for choosing a BMad development path and align the homepage, tutorials, Build documentation, workflow map, and Retrospective guidance with it.
Why
Developers need one clear model for scaling from an obvious edit to a session-sized Build run, a spec-backed epic, or a multi-epic project. The surrounding documentation also needs consistent boundaries between Build, Build Auto, and external orchestration.
How
Testing
Ran
HUSKY=0 npm ci && npm run qualitysuccessfully.