BMAD-METHOD/bmad/bmm/workflows/3-solutioning/architecture/checklist.md

Architecture Document Validation Checklist

Purpose: Validate the architecture document itself is complete, implementable, and provides clear guidance for AI agents.

Note: This checklist validates the ARCHITECTURE DOCUMENT only. For cross-workflow validation (PRD → Architecture → Stories alignment), use the solutioning-gate-check workflow.

---

1. Decision Completeness

All Decisions Made

• Every critical decision category has been resolved
• All important decision categories addressed
• No placeholder text like "TBD", "[choose]", or "{TODO}" remains
• Optional decisions either resolved or explicitly deferred with rationale

Decision Coverage

• Data persistence approach decided
• API pattern chosen
• Authentication/authorization strategy defined
• Deployment target selected
• All functional requirements have architectural support

---

2. Version Specificity

Technology Versions

• Every technology choice includes a specific version number
• Version numbers are current (verified via WebSearch, not hardcoded)
• Compatible versions selected (e.g., Node.js version supports chosen packages)
• Verification dates noted for version checks

Version Verification Process

• WebSearch used during workflow to verify current versions
• No hardcoded versions from decision catalog trusted without verification
• LTS vs. latest versions considered and documented
• Breaking changes between versions noted if relevant

---

3. Starter Template Integration (if applicable)

Template Selection

• Starter template chosen (or "from scratch" decision documented)
• Project initialization command documented with exact flags
• Starter template version is current and specified
• Command search term provided for verification

Starter-Provided Decisions

• Decisions provided by starter marked as "PROVIDED BY STARTER"
• List of what starter provides is complete
• Remaining decisions (not covered by starter) clearly identified
• No duplicate decisions that starter already makes

---

4. Novel Pattern Design (if applicable)

Pattern Detection

• All unique/novel concepts from PRD identified
• Patterns that don't have standard solutions documented
• Multi-epic workflows requiring custom design captured

Pattern Documentation Quality

• Pattern name and purpose clearly defined
• Component interactions specified
• Data flow documented (with sequence diagrams if complex)
• Implementation guide provided for agents
• Edge cases and failure modes considered
• States and transitions clearly defined

Pattern Implementability

• Pattern is implementable by AI agents with provided guidance
• No ambiguous decisions that could be interpreted differently
• Clear boundaries between components
• Explicit integration points with standard patterns

---

5. Implementation Patterns

Pattern Categories Coverage

• Naming Patterns: API routes, database tables, components, files
• Structure Patterns: Test organization, component organization, shared utilities
• Format Patterns: API responses, error formats, date handling
• Communication Patterns: Events, state updates, inter-component messaging
• Lifecycle Patterns: Loading states, error recovery, retry logic
• Location Patterns: URL structure, asset organization, config placement
• Consistency Patterns: UI date formats, logging, user-facing errors

Pattern Quality

• Each pattern has concrete examples
• Conventions are unambiguous (agents can't interpret differently)
• Patterns cover all technologies in the stack
• No gaps where agents would have to guess
• Implementation patterns don't conflict with each other

---

6. Technology Compatibility

Stack Coherence

• Database choice compatible with ORM choice
• Frontend framework compatible with deployment target
• Authentication solution works with chosen frontend/backend
• All API patterns consistent (not mixing REST and GraphQL for same data)
• Starter template compatible with additional choices

Integration Compatibility

• Third-party services compatible with chosen stack
• Real-time solutions (if any) work with deployment target
• File storage solution integrates with framework
• Background job system compatible with infrastructure

---

7. Document Structure

Required Sections Present

• Executive summary exists (2-3 sentences maximum)
• Project initialization section (if using starter template)
• Decision summary table with ALL required columns:
  • Category
  • Decision
  • Version
  • Rationale
• Project structure section shows complete source tree
• Implementation patterns section comprehensive
• Novel patterns section (if applicable)

Document Quality

• Source tree reflects actual technology decisions (not generic)
• Technical language used consistently
• Tables used instead of prose where appropriate
• No unnecessary explanations or justifications
• Focused on WHAT and HOW, not WHY (rationale is brief)

---

8. AI Agent Clarity

Clear Guidance for Agents

• No ambiguous decisions that agents could interpret differently
• Clear boundaries between components/modules
• Explicit file organization patterns
• Defined patterns for common operations (CRUD, auth checks, etc.)
• Novel patterns have clear implementation guidance
• Document provides clear constraints for agents
• No conflicting guidance present

Implementation Readiness

• Sufficient detail for agents to implement without guessing
• File paths and naming conventions explicit
• Integration points clearly defined
• Error handling patterns specified
• Testing patterns documented

---

9. Practical Considerations

Technology Viability

• Chosen stack has good documentation and community support
• Development environment can be set up with specified versions
• No experimental or alpha technologies for critical path
• Deployment target supports all chosen technologies
• Starter template (if used) is stable and well-maintained

Scalability

• Architecture can handle expected user load
• Data model supports expected growth
• Caching strategy defined if performance is critical
• Background job processing defined if async work needed
• Novel patterns scalable for production use

---

10. Common Issues to Check

Beginner Protection

• Not overengineered for actual requirements
• Standard patterns used where possible (starter templates leveraged)
• Complex technologies justified by specific needs
• Maintenance complexity appropriate for team size

Expert Validation

• No obvious anti-patterns present
• Performance bottlenecks addressed
• Security best practices followed
• Future migration paths not blocked
• Novel patterns follow architectural principles

---

Validation Summary

Document Quality Score

• Architecture Completeness: [Complete / Mostly Complete / Partial / Incomplete]
• Version Specificity: [All Verified / Most Verified / Some Missing / Many Missing]
• Pattern Clarity: [Crystal Clear / Clear / Somewhat Ambiguous / Ambiguous]
• AI Agent Readiness: [Ready / Mostly Ready / Needs Work / Not Ready]

Critical Issues Found

• Issue 1: **___**
• Issue 2: **___**
• Issue 3: **___**

Recommended Actions Before Implementation

1. ---

2. ---

3. ---

---

Next Step: Run the solutioning-gate-check workflow to validate alignment between PRD, Architecture, and Stories before beginning implementation.

---

This checklist validates architecture document quality only. Use solutioning-gate-check for comprehensive readiness validation.