mirror of
https://github.com/bmad-code-org/BMAD-METHOD.git
synced 2026-08-28 19:20:41 +08:00
Emmanuel Atsé
cede485217
* feat(docs): add sidebar order validator
Adds tools/validate-sidebar-order.js to validate sidebar.order values
in YAML frontmatter across English and translated docs.
Checks for duplicate orders, gaps in sequence, and missing order fields.
For translations, also warns on order drift from English counterparts.
Wired into the quality script as docs:validate-sidebar.
* fix(validate-sidebar): tighten language detection and drift guard, add docstrings
* fix(validate-sidebar): replace subdirectory heuristic with locale pattern matching
detectLanguageDirs() previously classified any top-level docs/ directory
containing subdirectories as a translation language. This was too broad —
if an English section ever gained nested subfolders it would be silently
excluded from validation.
Replaced with a BCP 47 locale-code regex (/^[a-z]{2}(?:-[a-zA-Z]{2})?$/)
that matches known patterns (cs, fr, vi-vn, zh-cn) and won't falsely
classify content sections like explanation/ or reference/.
* fix(validate-sidebar): guard drift check against undefined order values
extractSidebarOrder() returns { hasSidebar: false } when no sidebar block
exists, leaving order as undefined rather than null. The drift check only
guarded against null, allowing undefined values to emit noisy warnings
like "Order drift: ... order undefined".
Changed the guard to typeof === 'number' which correctly excludes both
undefined and null without relying on a specific sentinel value.
* chore(validate-sidebar): add JSDoc docstrings to all functions
Adds @param and @returns annotations to extractSidebarOrder,
detectLanguageDirs, getEnglishSections, checkDirectory,
checkTranslationDrift, and relativePath.
* fix(validate-sidebar): add to pre-commit hook
* refactor(validate-sidebar): harden parsing and edge-case handling
Refactor to main() wrapper with pure return-based APIs, single directory
scan, and shared reporting. Harden frontmatter parsing (anchored delimiter,
direct-child-only order extraction, flow mapping support) and validation
(Infinity/zero guard, gap flood cap, multi-segment locales, graceful ENOENT).
* docs: fix sidebar.order duplicates and gaps across all locales
Resolves all validator errors flagged by the new
tools/validate-sidebar-order.js check.
English (docs/{explanation,how-to,reference}/):
- Renumbered to remove duplicates; established reading order
for new explanation pages added since orders were last set.
Translations (cs, fr, vi-vn, zh-cn):
- Mirrored English structural ordering where files exist, then
compacted to 1..N within each directory to eliminate gaps
caused by missing translation files.
Non-blocking drift warnings remain where translation directories
have fewer files than English; these are expected per the
validator's design.
---------
Co-authored-by: Brian Madison <bmadcode@gmail.com>
2.7 KiB
2.7 KiB
title, description, sidebar
| title | description | sidebar | ||
|---|---|---|---|---|
| Why Solutioning Matters | Understanding why the solutioning phase is critical for multi-epic projects |
|
Phase 3 (Solutioning) translates what to build (from Planning) into how to build it (technical design). This phase prevents agent conflicts in multi-epic projects by documenting architectural decisions before implementation begins.
The Problem Without Solutioning
Agent 1 implements Epic 1 using REST API
Agent 2 implements Epic 2 using GraphQL
Result: Inconsistent API design, integration nightmare
When multiple agents implement different parts of a system without shared architectural guidance, they make independent technical decisions that may conflict.
The Solution With Solutioning
architecture workflow decides: "Use GraphQL for all APIs"
All agents follow architecture decisions
Result: Consistent implementation, no conflicts
By documenting technical decisions explicitly, all agents implement consistently and integration becomes straightforward.
Solutioning vs Planning
| Aspect | Planning (Phase 2) | Solutioning (Phase 3) |
|---|---|---|
| Question | What and Why? | How? Then What units of work? |
| Output | FRs/NFRs (Requirements) | Architecture + Epics/Stories |
| Agent | PM | Architect → PM |
| Audience | Stakeholders | Developers |
| Document | PRD (FRs/NFRs) | Architecture + Epic Files |
| Level | Business logic | Technical design + Work breakdown |
Key Principle
Make technical decisions explicit and documented so all agents implement consistently.
This prevents:
- API style conflicts (REST vs GraphQL)
- Database design inconsistencies
- State management disagreements
- Naming convention mismatches
- Security approach variations
When Solutioning is Required
| Track | Solutioning Required? |
|---|---|
| Quick Flow | No - skip entirely |
| BMad Method Simple | Optional |
| BMad Method Complex | Yes |
| Enterprise | Yes |
:::tip[Rule of Thumb] If you have multiple epics that could be implemented by different agents, you need solutioning. :::
The Cost of Skipping
Skipping solutioning on complex projects leads to:
- Integration issues discovered mid-sprint
- Rework due to conflicting implementations
- Longer development time overall
- Technical debt from inconsistent patterns
:::caution[Cost Multiplier] Catching alignment issues in solutioning is 10× faster than discovering them during implementation. :::