BMAD-METHOD/.patch/826/convention-analysis.md

Documentation Convention Analysis for PR #826

Date: 2025-10-28

---

Current BMAD Documentation Structure

Root-Level Documentation (Highly Restricted)

bmad-v6/
├── README.md              ← Project entry point, installation, quick start
├── CHANGELOG.md           ← Version history
├── CONTRIBUTING.md        ← Contribution guidelines
├── v6-open-items.md       ← Internal development tracking (temp)
└── LICENSE                ← License file

Pattern: Root .md files are limited to essential project metadata only.

Documentation Organization (docs/)

docs/
├── bmad-brownfield-guide.md          ← Guides (root of docs/)
├── v4-to-v6-upgrade.md               ← Guides (root of docs/)
├── conversion-report-*.md            ← Internal reports (root of docs/)
├── ide-info/                         ← Category: IDE-specific guides
│   ├── auggie.md
│   ├── claude-code.md
│   ├── cursor.md
│   ├── windsurf.md
│   └── ... (13 IDE guides)
└── installers-bundlers/              ← Category: Technical internals
    ├── ide-injections.md
    ├── installers-modules-platforms-reference.md
    └── web-bundler-usage.md

Pattern:

• Guides go directly in docs/ root if broadly applicable
• Categorized subdirectories for specific topics (ide-info/, installers-bundlers/)
• Kebab-case filenames

Missing Categories (Gaps)

Based on analysis, these logical categories don't yet exist:

• docs/planning/ - Would fit planning guides
• docs/guides/ - Could house methodology guides
• docs/references/ - Could house reference materials

---

Filename Convention Analysis

Pattern Observed

Root documentation (3 files):

• README.md (standard)
• CHANGELOG.md (standard)
• CONTRIBUTING.md (standard)
• v6-open-items.md (internal, kebab-case)

Docs directory (all kebab-case):

• bmad-brownfield-guide.md
• v4-to-v6-upgrade.md
• conversion-report-shard-doc-2025-10-26.md
• ide-injections.md
• installers-modules-platforms-reference.md
• web-bundler-usage.md

IDE info (all kebab-case):

• claude-code.md
• github-copilot.md
• auggie.md, etc.

Verdict: 100% consistent kebab-case for all documentation files.

PR #826 Filename

• Proposed: high-level-product-plan.md
• Evaluation: ✅ Follows kebab-case convention
• Issue: Name is vague; doesn't indicate it's a checklist/guide

Better alternatives:

• product-planning-checklist.md
• product-planning-considerations.md
• planning-reference.md

---

Content Pattern Analysis

Existing Documentation Characteristics

BMAD Guides (e.g., bmad-brownfield-guide.md):

• Explain BMAD methodology application
• Reference BMAD levels, phases, workflows
• Show CLI commands (bmad pm, agent triggers)
• Link to specific workflows and agents
• Practical, BMAD-integrated advice

Technical References (e.g., installers-modules-platforms-reference.md):

• Deep technical implementation details
• Architecture diagrams
• Code examples from BMAD codebase
• Installation and configuration specifics

Upgrade Guides (e.g., v4-to-v6-upgrade.md):

• Migration instructions
• Before/after comparisons
• BMAD workflow mapping
• Specific commands and file locations

PR #826 Content Characteristics

• Generic software planning checklist
• No BMAD methodology references
• No agent/workflow integration
• No CLI commands
• Could apply to any software project
• Reads like external reference material

Mismatch: Content doesn't follow BMAD documentation pattern of methodology integration.

---

Overlap Analysis

Existing BMAD Planning Documentation

In src/modules/bmm/workflows/:

• 2-plan-workflows/ - Contains PRD, tech-spec, architecture workflows
• 2-plan-workflows/README.md - Explains BMAD planning phases
• Individual workflow docs explain specific planning activities

In docs/:

• bmad-brownfield-guide.md - Covers planning considerations for existing projects
• v4-to-v6-upgrade.md - Mentions planning phase (PRD/Architecture)

PR #826 Coverage: Sections 1-8 overlap significantly with existing BMAD concepts:

1. Product Architecture → BMAD architect agent, architecture workflow
2. Technology Stack → Part of tech-spec workflow
3. Infrastructure & Deployment → Part of architecture planning
4. Data & Security → Part of tech-spec and architecture
5. User Experience → Covered in UX workflows
6. Scalability & Performance → Architecture considerations
7. Business & Operations → Part of project brief/PRD
8. Development Process → BMM workflow methodology

Verdict: ⚠️ High overlap with existing BMAD workflow coverage, but presented generically without BMAD integration.

---

Recommendations

Option 1: Relocate to docs/planning/ (Recommended)

Path: docs/planning/product-planning-checklist.md

Rationale:

• Creates logical category for planning guides
• Consistent with docs categorization pattern
• Clear, specific filename
• Allows for future planning guides

Required changes:

1. Create docs/planning/ directory
2. Move file with better name
3. Add BMAD integration section
4. Link to relevant workflows

Option 2: Integrate into Existing Guide

Path: Merge into docs/bmad-brownfield-guide.md as appendix

Rationale:

• Brownfield guide already covers planning considerations
• Avoids duplication
• Contextualizes within BMAD methodology

Required changes:

1. Add as "Appendix: Comprehensive Planning Checklist"
2. Reference BMAD agents/workflows for each section
3. Maintain single planning guide

Option 3: Enhance and Place at docs/product-planning-with-bmad.md

Path: docs/product-planning-with-bmad.md

Rationale:

• Top-level guide visibility
• Rewrite to be BMAD-first
• Transform generic checklist into BMAD methodology guide

Required changes:

1. Extensive rewrite with BMAD integration
2. Add agent/workflow references throughout
3. Include CLI examples
4. Link to specific workflow docs

---

Conclusion

Convention Compliance:

• ✅ Filename: Kebab-case (matches pattern)
• ❌ Placement: Root violation (should be in docs/)
• ❌ Content: Generic (should integrate BMAD)
• ⚠️ Organization: Missing logical category (suggest creating docs/planning/)

Recommended Action: Request relocation to docs/planning/product-planning-checklist.md with optional BMAD enhancement suggestions.