Validate architecture document completeness and quality against comprehensive checklist...
Validate architecture documents for completeness, quality, and adherence to best practices. Generates comprehensive validation report with quality score, identified gaps, and prioritized recommendations for improvement.
Core Principles:
Action: Read architecture document using bmad-commands
Execute:
python .claude/skills/bmad-commands/scripts/read_file.py \
--path {architecture_file} \
--output json
Parse document to extract:
Auto-detect from architecture content:
Frontend indicators:
Backend indicators:
Fullstack indicators:
If unable to detect: Prompt for project_type parameter
Validate required sections based on project type:
Score: +10 points per required section present
See: references/validation-rules.md for complete validation criteria and scoring rubrics
Check that all technology choices:
Scoring:
Flag unjustified technologies as gaps
Verify Non-Functional Requirements addressed:
| NFR Category | Required Elements |
|---|---|
| Performance | Response time targets, optimization strategies |
| Scalability | User growth plan, bottleneck identification |
| Security | Auth/authz, encryption, compliance |
| Reliability | Availability targets, fault tolerance |
| Maintainability | Code organization, testing strategy |
Scoring:
See: references/validation-rules.md for NFR validation criteria
Check Architecture Decision Records:
Quantity:
Quality (sample 3-5 ADRs):
Well-formed ADRs: +5 points Partial ADRs: +2 points Poor ADRs: 0 points
Validate security considerations:
Scoring:
Critical gap: Missing security section
Check scalability considerations:
Scoring:
Check deployment architecture:
Scoring:
Total possible points: 100
Score breakdown:
Quality Grades:
Validation passes if score ≥70
Categorize identified gaps:
Critical Gaps (blocking):
Major Gaps (important):
Minor Gaps (nice-to-have):
Priority: Critical → Major → Minor
Based on identified gaps, provide actionable recommendations:
Recommendation format:
**Priority:** Critical | Major | Minor
**Gap:** [Specific missing element]
**Recommendation:** [Concrete action to take]
**Impact:** [Why this matters]
**Effort:** [Estimated time to address]
Example:
**Priority:** Critical
**Gap:** Security architecture section missing
**Recommendation:** Add security architecture section covering authentication, authorization, encryption, and input validation
**Impact:** Security is fundamental for production readiness
**Effort:** 2-3 hours
See: references/templates.md for recommendation and report templates
Create comprehensive validation report:
# Architecture Validation Report
**Architecture:** [file path]
**Project Type:** [detected type]
**Validation Date:** [timestamp]
**Validation Result:** PASS | FAIL
---
## Quality Score: [score]/100
**Grade:** [A/B/C/D/F]
**Score Breakdown:**
- Completeness: [X]/40
- Technology Stack: [X]/15
- NFR Coverage: [X]/15
- ADRs: [X]/15
- Security: [X]/10
- Scalability: [X]/10
- Deployment: [X]/10
---
## Sections Present
✅ System Overview
✅ Component Architecture (Frontend)
✅ Technology Stack
❌ Security Architecture (MISSING)
⚠️ Scalability Plan (Incomplete)
---
## Gaps Identified
### Critical Gaps
1. Security architecture section missing
2. No NFR coverage
### Major Gaps
3. Only 2 ADRs (minimum 3 required)
4. Technology choices not justified
### Minor Gaps
5. Monitoring not discussed
6. Disaster recovery not mentioned
---
## Recommendations
### 1. Add Security Architecture (Critical)
**Gap:** Security section missing
**Action:** Document authentication, authorization, encryption, input validation
**Impact:** Production readiness blocker
**Effort:** 2-3 hours
### 2. Address NFRs (Critical)
**Gap:** Zero NFR coverage
**Action:** Add sections for performance targets, scalability plan, reliability targets
**Impact:** Architecture may not meet requirements
**Effort:** 1-2 hours
[... continue for all gaps ...]
---
## Summary
**Overall Assessment:** [Summary paragraph]
**Next Steps:**
1. Address all critical gaps
2. Address major gaps
3. Re-run validation
4. Proceed to implementation when score ≥70
---
**Validation Tool:** BMAD Enhanced validate-architecture skill
**Validated by:** Winston (Architect)
Result: PASS with minor recommendations Action: Proceed to implementation, optionally address minor gaps
Result: PASS with major recommendations Action: Address major gaps before implementation
Result: FAIL Action: Address all critical and major gaps, then re-validate
Result: FAIL (auto-fail for missing critical sections) Action: Add missing sections, re-validate
When enabled (--strict):
Use strict mode for:
references/validation-rules.md - Comprehensive validation rules, scoring criteria, and rubrics for all dimensionsreferences/templates.md - Validation report templates, recommendation formats, and output structuresreferences/examples.md - Complete validation examples showing PASS (85/100), borderline PASS (72/100), and FAIL (42/100) scenariosEscalate to user when:
Part of BMAD Enhanced Quality Suite
