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

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 bold paragraphs for callouts | Use admonitions instead |
| 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
@ -37,7 +37,7 @@ These rules apply to ALL document types. Violations fail review.
- `###` subsections: 2-3 per `##` section max
- `####`: 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
@ -114,7 +114,7 @@ Critical warnings only — data loss, security issues
### Rules
- Always include a title
- Keep content to 1-3 sentences
- Keep content to 1-3 sentences (longer rarely needed)
- Never nest admonitions
## Tables
@ -554,16 +554,16 @@ Structure:
```md
## Questions
- [Question one?](#question-one)
- [Question two?](#question-two)
- [Do I always need architecture?](#do-i-always-need-architecture)
- [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](...).
```