ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity

docs: address PR review findings for style guide 

- Fix forward reference in Header Budget section
- Clarify descriptions rule scope (tables and 5+ item lists)
- Restore realistic FAQ examples
- Add qualifier to admonition content length guideline

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Alex Verkhovsky 2026-01-13 14:34:48 -08:00
parent fbfbbb0f16
commit ebf86ea1f4
1 changed files with 9 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
docs/_STYLE_GUIDE.md
View File

@ -17,7 +17,7 @@ These rules apply to ALL document types. Violations fail review.
| No code blocks for non-code | Confusing semantics | | No code blocks for non-code | Confusing semantics |
| No bold paragraphs for callouts | Use admonitions instead | | No bold paragraphs for callouts | Use admonitions instead |
| 1-2 admonitions per section max | Overuse creates noise | | 1-2 admonitions per section max | Overuse creates noise |
| Descriptions 1-2 sentences max | Longer belongs in dedicated docs | | Table cells and long list items (5+) 1-2 sentences max | Walls of text; break into sections or link to details |
## Visual Hierarchy ## Visual Hierarchy
@ -37,7 +37,7 @@ These rules apply to ALL document types. Violations fail review.
- `###` subsections: 2-3 per `##` section max - `###` subsections: 2-3 per `##` section max
- `####`: Never use - `####`: Never use
Structure templates below show content flow, not 1:1 header mapping. Admonitions and inline elements appear within sections, not as separate headers. The structure templates in this guide show content flow, not 1:1 header mapping. Admonitions and inline elements appear within sections, not as separate headers.
### Header Naming ### Header Naming
@ -114,7 +114,7 @@ Critical warnings only — data loss, security issues
### Rules ### Rules
- Always include a title - Always include a title
- Keep content to 1-3 sentences - Keep content to 1-3 sentences (longer rarely needed)
- Never nest admonitions - Never nest admonitions
## Tables ## Tables
@ -554,16 +554,16 @@ Structure:
```md ```md
## Questions ## Questions
- [Question one?](#question-one) - [Do I always need architecture?](#do-i-always-need-architecture)
- [Question two?](#question-two) - [Can I change my plan later?](#can-i-change-my-plan-later)
### Question one? ### Do I always need architecture?
Direct answer without "A:" prefix. Only for BMad Method and Enterprise tracks. Quick Flow skips to implementation.
### Question two? ### Can I change my plan later?
Direct answer. Yes. The SM agent has a `correct-course` workflow for handling scope changes.
**Have a question not answered here?** [Open an issue](...) or ask in [Discord](...). **Have a question not answered here?** [Open an issue](...) or ask in [Discord](...).
``` ```