architecture-validation

Architecture Validation Skill

Dynamically validate that the implemented codebase matches the architectural decisions, design patterns, and system constraints documented in ANY plan files found in the plans/ directory.

Purpose

This skill provides a generic, adaptive framework for architecture validation that:

• Discovers all plan files in plans/ directory
• Extracts architectural requirements, decisions, and constraints dynamically
• Validates implementation compliance without hardcoded assumptions
• Reports gaps, drift, and violations with actionable recommendations

Key Principle: Be architecture-agnostic. Work with ANY project structure and ANY set of plans.

When to Use This Skill

Use this skill when:

• Validating that implementation matches planning documents
• Checking for architecture drift after development
• Ensuring design decisions are being followed
• Identifying missing or incomplete implementations
• Auditing compliance with documented constraints
• Preparing for architecture reviews
• Verifying refactoring didn't break architectural boundaries

Validation Dimensions

The skill validates across multiple dimensions, dynamically discovered from plan files:

1. Component/​Module Structure

• Planned crates, packages, modules exist
• Directory organization matches plans
• Component boundaries are maintained

2. Dependency Architecture

• Dependency rules are followed
• No circular dependencies
• Proper abstraction layers
• No unwanted dependencies

3. Data Models

• Structs, enums, types match plans
• Required fields present
• Schemas implemented correctly

4. APIs and Interfaces

• Public APIs match planned signatures
• Required functions exist
• Traits/​interfaces implemented

5. Performance Architecture

• Benchmarks exist for targets
• Performance requirements documented
• Resource limits implemented

6. Security Architecture

• Security measures implemented
• Attack surfaces addressed
• Input validation present
• No hardcoded secrets

7. Testing Strategy

• Test types match plan
• Coverage requirements met
• Test infrastructure present

8. Integration Patterns

• External integrations match design
• Communication patterns correct
• Protocol implementations compliant

Validation Workflow

Phase 1: Plan Discovery

# Find all plan files
ls -1 plans/​*.md

# Read plan index
cat plans/​README.md

Output: List of all plan files to analyze

Phase 2: Architecture Extraction

# Extract components/​crates
grep -rh "crate\|component\|module" plans/ | sort -u

# Extract dependencies
grep -rh "depend\|flow\|import" plans/ | sort -u

# Extract performance targets
grep -rh "target\|metric\|<.*ms\|P[0-9]" plans/ | sort -u

# Extract security requirements
grep -rh "security\|threat\|attack" plans/ -i | sort -u

# Extract data models
grep -rh "struct\|enum\|type\|schema" plans/ | sort -u

Output: Structured list of architectural elements

Phase 3: Codebase Analysis

# Analyze project structure
find . -name "Cargo.toml" -not -path "*/​target/​*"
tree -L 2 -I target

# Analyze dependencies
cargo tree --depth 1
cargo tree --duplicates

# Analyze code
rg "pub (async )?fn|pub struct|pub enum" --type rust

Output: Actual implementation state

Phase 4: Compliance Validation

For each discovered architectural element:

1. Check if it exists in codebase
2. Validate it matches specification
3. Assess compliance level
4. Document findings

Output: Compliance matrix

Phase 5: Gap Analysis

Identify:

• Missing: Planned but not implemented
• Drift: Implemented differently than planned
• Extra: Implemented but not documented

Output: Gap report with priorities

Phase 6: Report Generation

Generate comprehensive report with:

• Executive summary
• Detailed findings per dimension
• Specific recommendations
• Action items with priorities

Extraction Patterns

Components/​Crates

Look for:

• "crate", "component", "module", "package"
• Directory tree structures in code blocks
• Architecture diagrams
• Component lists

Dependencies

Look for:

• "depends on", "imports", "requires"
• "must not depend", "should not import"
• "flow:", "→", "-->", "⇒"
• Dependency rules and constraints

Performance

Look for:

• "target:", "metric:", "goal:"
• "<Xms", "P95", "P99", "latency", "throughput"
• Performance requirements tables
• Benchmark specifications

Security

Look for:

• "security", "threat", "attack", "vulnerability"
• "sanitize", "validate", "authenticate"
• Security requirement lists
• Attack surface descriptions

Data Models

Look for:

• "struct", "enum", "type", "interface"
• "table", "schema", "field", "column"
• Data model diagrams
• Type definitions

APIs

Look for:

• "pub fn", "public function", "API"
• "endpoint", "method", "operation"
• Function signatures
• Interface definitions

Compliance Levels

✅ Compliant

• Architectural element fully implemented as planned
• No deviations
• All requirements met

⚠️ Partial

• Element exists but incomplete
• Some requirements met, others missing
• Functional but not fully compliant

❌ Non-Compliant

• Element missing entirely
• Significant violations
• Major architectural drift

Report Format

# Architecture Validation Report
**Date**: [Date]
**Project**: [Name]
**Plans**: [List of plan files]

## Executive Summary
- Overall Compliance: X%
- Critical Issues: N
- Warnings: M
- Info: K

## Plans Analyzed
1. plans/​00-overview.md - Project overview
2. plans/​01-understand.md - Requirements
...

## Architectural Elements Discovered
[Dynamic list based on plan extraction]

### Components
- Component A: ✅ Implemented
- Component B: ⚠️ Partial
- Component C: ❌ Missing

### Dependencies
- Rule 1: ✅ Compliant
- Rule 2: ❌ Violated

### Performance
- Target 1 (<100ms): ⚠️ Untested
- Target 2 (>1000 ops/​s): ✅ Met

### Security
- Requirement 1: ✅ Implemented
- Requirement 2: ⚠️ Partial

## Detailed Findings

### ✅ Fully Compliant
[List compliant aspects]

### ⚠️ Partial Compliance
[List partial implementations with details]

### ❌ Non-Compliant
[List violations with:
- Plan reference (file:line)
- Expected vs Actual
- Impact assessment
- Priority
- Recommended action]

## Architecture Drift
[List intentional or unintentional deviations]

## Recommendations
### High Priority
[Critical items]

### Medium Priority
[Important items]

### Low Priority
[Nice to have items]

## Next Steps
[Actionable next steps]

Example Usage

Scenario 1: Initial Validation

# After reading all plan files
# Extract 50+ architectural elements
# Validate against codebase
# Generate report: 75% compliance, 5 critical issues

Scenario 2: Post-Refactoring

# Re-validate after major changes
# Check for new violations
# Verify planned improvements implemented
# Generate diff report

Scenario 3: Architecture Review Prep

# Comprehensive validation
# Document all drift
# Prepare justifications
# Generate presentation-ready report

Integration with Agent

This skill is used by the architecture-validator agent to:

1. Provide validation patterns and utilities
2. Define report formats
3. Establish compliance criteria
4. Guide systematic validation process

Validation Commands

Discovery

# Find all plans
ls -1 plans/​*.md | wc -l

# Check plan structure
head -20 plans/​README.md

Extraction

# Extract all architectural keywords
for file in plans/​*.md; do
  echo "=== $file ==="
  grep -i "decision:\|requirement:\|target:\|constraint:" "$file"
done

Analysis

# Compare planned vs actual
echo "Planned crates:" && grep -rh "crate" plans/ | wc -l
echo "Actual crates:" && find . -name "Cargo.toml" | wc -l

Validation

# Check specific requirement
grep -r "requirement X" plans/
rg "implementation of X" --type rust

Best Practices

1. Start with README: Read plans/​README.md first to understand structure
2. Read all plans: Don't skip any plan files
3. Extract systematically: Use consistent patterns across all files
4. Be specific: Always reference exact file and line numbers
5. Assess impact: Explain why violations matter
6. Provide solutions: Give clear remediation steps
7. Track evolution: Compare current vs previous validations

Edge Cases

• No plans folder: Report that validation cannot proceed
• Empty plans: Report insufficient documentation
• Conflicting plans: Flag conflicts for resolution
• Outdated plans: Note discrepancies and suggest updates
• Ambiguous plans: Request clarification
• Multiple architectures: Validate each separately

Metrics

Track validation quality:

• Plan Coverage: % of plan files analyzed
• Element Coverage: % of architectural elements checked
• Validation Depth: How thoroughly each element validated
• Finding Quality: Specificity and actionability of findings
• Report Completeness: All sections filled out

Self-Learning Framework

This skill enables self-learning and continuous improvement by learning from validation results.

Learning Cycle

Validate → Identify Issues → Analyze Root Cause → Update Documentation → Re-validate
    ↑                                                                            ↓
    └────────────────────────── Feedback Loop ──────────────────────────────────┘

Learning Triggers

Trigger 1: Repeated Violations

• Same violation appears 3+ times
• May indicate plan is outdated or unrealistic
• Action: Review and potentially update plan

Trigger 2: False Positives

• Validator reports violations for correct code
• Indicates validation logic needs refinement
• Action: Update agent/​skill validation patterns

Trigger 3: New Patterns Emerge

• Implementation uses patterns not documented
• Patterns appear beneficial
• Action: Document new patterns in plans

Trigger 4: Plan-Reality Mismatch

• Consistent drift between plan and implementation
• Implementation is actually better
• Action: Update plan to reflect reality

Self-Update Protocol

Phase 1: Detect Learning Opportunity

# After validation, analyze:
# - Number of violations by type
# - Pattern frequency
# - False positive rate
# - User feedback on findings

# If thresholds exceeded, trigger learning

Phase 2: Root Cause Analysis

# Determine root cause:
# - Is the plan outdated? → Update plan
# - Is validation incomplete? → Update agent/​skill
# - Is implementation wrong? → Report to user
# - Is this a new valid pattern? → Document pattern

Phase 3: Update Documentation

# Update appropriate files:

# Option A: Update Plans
# - plans/​00-overview.md: If project scope changed
# - plans/​01-understand.md: If requirements changed
# - plans/​02-plan.md: If architecture evolved
# - plans/​03-execute.md: If implementation patterns changed
# - plans/​04-review.md: If quality criteria changed
# - plans/​05-secure.md: If security model changed
# - plans/​06-feedback-loop.md: Document the learning

# Option B: Update Agent/​Skill
# - .claude/​agents/​architecture-validator.md: Update validation logic
# - .claude/​skills/​architecture-validation/​SKILL.md: Update patterns

# Option C: Update Other Claude Files
# - .claude/​CLAUDE.md: If workflow changes
# - Related skill files: If validation changes affect them

Phase 4: Verification

# After updates:
# 1. Re-run validation
# 2. Confirm issue resolved
# 3. Check for new issues
# 4. Document learning

Learning Examples

Example 1: Outdated Dependency Rule

Violation: "Core depends on storage implementation"
Frequency: 10 occurrences
Analysis: Dependency is intentional and beneficial
Learning: Rule too strict for current architecture
Action:
  1. Edit plans/​02-plan.md: Update dependency rules
  2. Document rationale: "Direct dependency acceptable for X reason"
  3. Edit architecture-validator.md: Remove overly strict check
  4. Document in plans/​06-feedback-loop.md

Example 2: Missing Validation Pattern

Issue: New async pattern not validated
Frequency: 5 instances found manually
Analysis: Validation extraction patterns incomplete
Learning: Need to check for async patterns
Action:
  1. Edit architecture-validator.md: Add async pattern checks
  2. Edit SKILL.md: Document async validation
  3. Re-run validation: Confirm new patterns detected

Example 3: New Architecture Pattern

Discovery: Code uses Circuit Breaker pattern
Status: Not documented in plans
Analysis: Pattern is beneficial, should be standard
Learning: Update plans to include pattern
Action:
  1. Edit plans/​02-plan.md: Add Circuit Breaker section
  2. Edit plans/​03-execute.md: Document implementation
  3. Edit architecture-validator.md: Validate circuit breakers
  4. Document in plans/​06-feedback-loop.md

Files to Update

Plans (plans/):

• Update when architecture evolves
• Document new patterns
• Revise constraints
• Add learnings to 06-feedback-loop.md

Agent (.claude/​agents/​architecture-validator.md):

• Update validation logic
• Add new extraction patterns
• Refine reporting
• Document self-learning improvements

Skill (.claude/​skills/​architecture-validation/​SKILL.md):

• Update validation dimensions
• Add new patterns
• Refine workflows
• Document examples

Other Claude Files (.claude/):

• CLAUDE.md: Update if workflow changes
• Related skills: Update if validation changes affect them
• Agent coordination files: Update if dependencies change

Learning Metrics

Track learning effectiveness:

• Learning Rate: Updates per week
• False Positive Reduction: % decrease over time
• Coverage Improvement: New patterns detected
• Plan Accuracy: Plan-reality alignment
• Validation Quality: User satisfaction with findings

Learning History Format

In plans/​06-feedback-loop.md:

## Architecture Validator Learnings

### [Date]: Dependency Rule Refinement
**Issue**: Core-Storage dependency flagged incorrectly
**Analysis**: Rule too strict, dependency is intentional
**Action**: Updated plans/​02-plan.md lines 45-50
**Result**: False positives reduced from 10 to 0
**Status**: ✅ Verified

### [Date]: New Pattern Recognition
**Issue**: Circuit Breaker pattern not validated
**Analysis**: Pattern is widely used, should validate
**Action**: Updated architecture-validator.md, added extraction
**Result**: Now detects 5 instances of pattern
**Status**: ✅ Verified

Continuous Improvement

Weekly Review:

• Review validation results
• Identify improvement opportunities
• Update documentation
• Refine validation logic

Monthly Retrospective:

• Assess learning metrics
• Major architecture changes
• Plan substantial updates
• Validate learning effectiveness

Quarterly Audit:

• Comprehensive review of plans
• Major agent/​skill updates
• Architecture evolution assessment
• Long-term pattern analysis

Updates and Versioning

Version 2.0.0 Changes:

• Made validation fully generic and plan-driven
• Removed hardcoded architectural assumptions
• Added dynamic element extraction
• Enhanced pattern matching capabilities
• Improved report generation
• Added comprehensive edge case handling
• Added self-learning and adaptation framework
• Integrated feedback loop for continuous improvement
• Enabled automatic plan and agent updates

Related Skills

• plan-gap-analysis: Analyzes gaps between plans and implementation
• rust-code-quality: Validates Rust-specific code quality
• code-reviewer: Reviews code changes for quality
• episode-complete: For recording validation learnings in memory system

Resources

• Agent: .claude/​agents/​architecture-validator.md
• Plans: plans/​*.md
• Project guidelines: AGENTS.md, CLAUDE.md
• Learning history: plans/​06-feedback-loop.md

---

Last Updated: 2025-11-12 Status: Active Maintenance: Self-updating based on validation learnings Learning Enabled: Yes