Agent Skills: Validate Architecture

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:

| 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:

• 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