Validate Architecture

Purpose

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:

• •Comprehensive checklists: Cover all architectural dimensions
• •Objective scoring: Consistent, repeatable quality measurement
• •Actionable feedback: Specific, prioritized improvements
• •Adapt to context: Different criteria for different project types

Prerequisites

• •Architecture document exists (docs/architecture.md or specified path)
• •Architecture follows standard structure (see create-architecture skill)

Workflow

1. Load Architecture Document

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:

• •Present sections
• •Technology stack components
• •ADRs count and quality
• •NFRs coverage
• •Security considerations
• •Scalability mentions

2. Detect Project Type

Auto-detect from architecture content:

Frontend indicators:

• •Component architecture section
• •State management discussion
• •UI/routing mentions
• •Frontend technologies (React, Vue, etc.)

Backend indicators:

• •API design section
• •Service layer architecture
• •Database/data layer
• •Backend technologies (Node, Python, etc.)

Fullstack indicators:

• •Both frontend and backend sections
• •Integration/API contract sections
• •End-to-end authentication flow
• •Full stack technologies (Next.js, etc.)

If unable to detect: Prompt for project_type parameter

3. Run Completeness Checklist

Validate required sections based on project type:

Universal Sections (All Types)

• •✅ System Overview (purpose, users, features)
• •✅ Technology Stack (with justifications)
• •✅ Deployment Architecture
• •✅ Security Architecture
• •✅ Architecture Decision Records (≥3)

Frontend-Specific Sections

• •✅ Component Architecture
• •✅ State Management Strategy
• •✅ Routing Design
• •✅ Styling Approach
• •✅ Build & Deployment Pipeline

Backend-Specific Sections

• •✅ API Design (REST/GraphQL/tRPC)
• •✅ Service Layer Architecture
• •✅ Data Architecture & Modeling
• •✅ Integration Patterns
• •✅ Error Handling Strategy

Fullstack-Specific Sections

• •✅ End-to-End Integration
• •✅ API Contracts/Type Safety
• •✅ Authentication & Authorization Flow
• •✅ Frontend-Backend Communication
• •✅ Unified Deployment Strategy

Score: +10 points per required section present

See: references/validation-rules.md for complete validation criteria and scoring rubrics

4. Validate Technology Stack

Check that all technology choices:

• •✅ Are documented (not just mentioned)
• •✅ Have justifications (why this choice?)
• •✅ List alternatives considered
• •✅ Explain trade-offs
• •✅ Are appropriate for project scale

Scoring:

• •All choices justified: +15 points
• •Most choices justified: +10 points
• •Some justified: +5 points
• •None justified: 0 points

Flag unjustified technologies as gaps

5. Assess NFR Coverage

Verify Non-Functional Requirements addressed:

Scoring:

• •All NFRs addressed: +15 points
• •Most NFRs addressed: +10 points
• •Some NFRs addressed: +5 points
• •Few/none addressed: 0 points

See: references/validation-rules.md for NFR validation criteria

6. Evaluate ADRs Quality

Check Architecture Decision Records:

Quantity:

• •≥10 ADRs: +10 points
• •5-9 ADRs: +7 points
• •3-4 ADRs: +5 points
• •<3 ADRs: 0 points

Quality (sample 3-5 ADRs):

• •✅ Context clearly stated
• •✅ Decision explicitly stated
• •✅ Alternatives considered (≥2)
• •✅ Rationale provided
• •✅ Consequences documented

Well-formed ADRs: +5 points Partial ADRs: +2 points Poor ADRs: 0 points

7. Check Security Posture

Validate security considerations:

• •✅ Authentication mechanism defined
• •✅ Authorization strategy documented
• •✅ Data encryption (at rest, in transit)
• •✅ Input validation approach
• •✅ Security best practices mentioned
• •✅ Compliance requirements (if applicable)

Scoring:

• •Comprehensive security: +10 points
• •Basic security: +5 points
• •Minimal security: 0 points

Critical gap: Missing security section

8. Assess Scalability Planning

Check scalability considerations:

• •✅ User growth projections
• •✅ Scaling strategy (horizontal/vertical)
• •✅ Bottleneck identification
• •✅ Load balancing approach
• •✅ Database scaling plan
• •✅ Caching strategy

Scoring:

• •Detailed scalability plan: +10 points
• •Basic scalability mentions: +5 points
• •No scalability planning: 0 points

9. Validate Deployment Strategy

Check deployment architecture:

• •✅ Deployment platform specified
• •✅ Environment strategy (dev, staging, prod)
• •✅ CI/CD pipeline outlined
• •✅ Monitoring and observability
• •✅ Backup and disaster recovery

Scoring:

• •Comprehensive deployment: +10 points
• •Basic deployment: +5 points
• •Missing deployment: 0 points

10. Calculate Quality Score

Total possible points: 100

Score breakdown:

• •Completeness (sections): 30-40 points (varies by type)
• •Technology justifications: 15 points
• •NFR coverage: 15 points
• •ADRs quantity & quality: 15 points
• •Security posture: 10 points
• •Scalability planning: 10 points
• •Deployment strategy: 10 points

Quality Grades:

• •90-100: Excellent (A)
• •80-89: Good (B)
• •70-79: Acceptable (C)
• •60-69: Needs Improvement (D)
• •<60: Insufficient (F)

Validation passes if score ≥70

11. Identify Gaps

Categorize identified gaps:

Critical Gaps (blocking):

• •Missing security section
• •No technology justifications
• •Fewer than 3 ADRs
• •Zero NFR coverage

Major Gaps (important):

• •Missing key sections for project type
• •Poor ADR quality
• •Minimal security details
• •No scalability planning

Minor Gaps (nice-to-have):

• •Incomplete deployment details
• •Missing diagrams
• •Light monitoring discussion

Priority: Critical → Major → Minor

12. Generate Recommendations

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

13. Generate Validation Report

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)

Common Scenarios

Scenario 1: High-Quality Architecture (Score 85+)

Result: PASS with minor recommendations Action: Proceed to implementation, optionally address minor gaps

Scenario 2: Acceptable Architecture (Score 70-79)

Result: PASS with major recommendations Action: Address major gaps before implementation

Scenario 3: Insufficient Architecture (Score <70)

Result: FAIL Action: Address all critical and major gaps, then re-validate

Scenario 4: Missing Critical Sections

Result: FAIL (auto-fail for missing critical sections) Action: Add missing sections, re-validate

Strict Mode

When enabled (--strict):

• •Minimum score: 80 (instead of 70)
• •All major gaps must be addressed
• •ADR quality rigorously checked
• •More detailed NFR validation

Use strict mode for:

• •Production systems
• •High-complexity projects
• •Compliance-sensitive applications
• •Enterprise deployments

Best Practices

1. •Run early and often - Validate during architecture creation, not after
2. •Address critical gaps immediately - Don't proceed with critical gaps
3. •Iterate - Re-validate after addressing gaps
4. •Use as checklist - Reference validation checklist while creating architecture
5. •Don't over-optimize - Score of 70-80 is usually sufficient for implementation

Reference Files

• •references/validation-rules.md - Comprehensive validation rules, scoring criteria, and rubrics for all dimensions
• •references/templates.md - Validation report templates, recommendation formats, and output structures
• •references/examples.md - Complete validation examples showing PASS (85/100), borderline PASS (72/100), and FAIL (42/100) scenarios

When to Escalate

Escalate to user when:

• •Architecture file not found or unreadable
• •Unable to detect project type automatically
• •Score is below 50 (major rework needed)
• •Critical compliance issues detected
• •Architecture deviates significantly from standards

Part of BMAD Enhanced Quality Suite