Architect Review Methodology Skill

When to Use This Skill

Use this skill when implementing architect review methodology patterns in your codebase.

How to Use This Skill

Review the patterns and examples below
Apply the relevant patterns to your implementation
Follow the best practices outlined in this skill

Architecture review process, design validation, and technical assessment.

Core Capabilities

Review Process - Structured architecture evaluation
Quality Attributes - NFR validation (ATAM-inspired)
Risk Analysis - Technical debt and risk identification
Trade-off Analysis - Decision impact assessment
Documentation - Review findings and recommendations

Architecture Review Framework

# Architecture Review Template

## 1. Review Metadata

| Field | Value |
|-------|-------|
| **System** | {System name} |
| **Version** | {Architecture version} |
| **Review Date** | {YYYY-MM-DD} |
| **Reviewers** | {Names and roles} |
| **Review Type** | Initial / Milestone / Pre-Production |

## 2. Business Context

### Business Drivers
- {Driver 1: e.g., Scale to 1M users by Q4}
- {Driver 2: e.g., Reduce operational costs by 30%}
- {Driver 3: e.g., Enter new market segment}

### Constraints
- {Constraint 1: e.g., Must use existing PostgreSQL infrastructure}
- {Constraint 2: e.g., Team has limited Kubernetes experience}
- {Constraint 3: e.g., Budget cap of $50K/month}

## 3. Quality Attribute Scenarios

### Performance
| Scenario | Stimulus | Response | Measure | Priority |
|----------|----------|----------|---------|----------|
| Peak load | 10K concurrent requests | Process all requests | p99 < 200ms | P0 |
| Batch processing | 1M records import | Complete processing | < 1 hour | P1 |

### Availability
| Scenario | Stimulus | Response | Measure | Priority |
|----------|----------|----------|---------|----------|
| Component failure | Single node crash | System remains operational | 99.9% uptime | P0 |
| Database failover | Primary DB failure | Automatic failover | RTO < 30s | P0 |

### Security
| Scenario | Stimulus | Response | Measure | Priority |
|----------|----------|----------|---------|----------|
| Authentication bypass | Malicious request | Block and alert | 0 successful bypasses | P0 |
| Data breach attempt | SQL injection | Sanitize and log | 0 data exposure | P0 |

### Scalability
| Scenario | Stimulus | Response | Measure | Priority |
|----------|----------|----------|---------|----------|
| Traffic spike | 5x normal load | Auto-scale | Scale within 2 min | P1 |
| Data growth | 10x data volume | Handle gracefully | No degradation | P1 |

## 4. Architecture Analysis

### Component Review

| Component | Purpose | Technology | Concerns | Risk Level |
|-----------|---------|------------|----------|------------|
| API Gateway | Request routing | Kong | Single point of failure | Medium |
| Auth Service | Authentication | Keycloak | Complexity | Low |
| Core API | Business logic | Node.js | Technical debt | High |
| Database | Data persistence | PostgreSQL | Scaling limits | Medium |

### Dependency Analysis

┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Client │────>│ API Gateway │────>│ Auth Svc │ └─────────────┘ └─────────────┘ └─────────────┘ │ v ┌─────────────┐ │ Core API │ └─────────────┘ │ ┌────────────┼────────────┐ v v v ┌─────────┐ ┌─────────┐ ┌─────────┐ │ DB │ │ Cache │ │ Queue │ └─────────┘ └─────────┘ └─────────┘

### Interface Contracts
- [ ] API contracts defined (OpenAPI/GraphQL schema)
- [ ] Event schemas documented (AsyncAPI)
- [ ] Database migrations versioned
- [ ] External API dependencies documented

## 5. Risk Assessment

### Technical Risks

| Risk | Probability | Impact | Mitigation | Owner |
|------|-------------|--------|------------|-------|
| Database bottleneck | High | High | Read replicas, caching | DBA |
| Single point of failure | Medium | High | HA configuration | DevOps |
| Security vulnerability | Low | Critical | Security audit, WAF | Security |
| Vendor lock-in | Medium | Medium | Abstraction layers | Architect |

### Architecture Debt

| Item | Description | Effort | Priority | Status |
|------|-------------|--------|----------|--------|
| Monolith coupling | Tight coupling between modules | 3 sprints | P1 | Open |
| Missing observability | No distributed tracing | 1 sprint | P0 | Open |
| Outdated dependencies | 15 packages need updates | 2 sprints | P2 | Open |

## 6. Trade-off Analysis

### Decision: Microservices vs Monolith

| Factor | Microservices | Monolith | Weight |
|--------|---------------|----------|--------|
| Scalability | ✅ Independent scaling | ❌ Scale entire app | 0.3 |
| Complexity | ❌ Distributed systems | ✅ Simpler | 0.2 |
| Team structure | ✅ Team autonomy | ❌ Coordination needed | 0.2 |
| Development speed | ❌ Slower initially | ✅ Faster initially | 0.15 |
| Operational cost | ❌ Higher | ✅ Lower | 0.15 |

**Recommendation:** Start with modular monolith, extract services when needed.

## 7. Recommendations

### Immediate Actions (P0)
1. [ ] Implement distributed tracing (Jaeger/Zipkin)
2. [ ] Add circuit breakers to external service calls
3. [ ] Configure horizontal auto-scaling

### Short-term Improvements (P1)
1. [ ] Migrate to managed database service
2. [ ] Implement event-driven communication
3. [ ] Add comprehensive API documentation

### Long-term Considerations (P2)
1. [ ] Evaluate service extraction candidates
2. [ ] Plan for multi-region deployment
3. [ ] Consider GraphQL federation

## 8. Review Verdict

**Overall Assessment:** ⚠️ Conditionally Approved

**Summary:** Architecture is fundamentally sound but requires addressing P0 items before production deployment.

**Next Review:** {Date for follow-up review}

---

**Signatures:**
- Lead Architect: _________________ Date: _______
- Tech Lead: _________________ Date: _______
- Product Owner: _________________ Date: _______

Quality Attribute Evaluation

// src/architecture/quality-evaluator.ts
interface QualityScenario {
  attribute: QualityAttribute;
  stimulus: string;
  environment: string;
  response: string;
  measure: string;
  priority: 'P0' | 'P1' | 'P2';
}

enum QualityAttribute {
  Performance = 'performance',
  Availability = 'availability',
  Security = 'security',
  Scalability = 'scalability',
  Maintainability = 'maintainability',
  Testability = 'testability',
  Deployability = 'deployability',
  Observability = 'observability',
}

interface EvaluationResult {
  scenario: QualityScenario;
  status: 'met' | 'partially_met' | 'not_met' | 'untested';
  evidence: string;
  gaps: string[];
  recommendations: string[];
}

export class QualityAttributeEvaluator {
  evaluateScenario(scenario: QualityScenario, architecture: ArchitectureSpec): EvaluationResult {
    const evaluators: Record<QualityAttribute, () => EvaluationResult> = {
      [QualityAttribute.Performance]: () => this.evaluatePerformance(scenario, architecture),
      [QualityAttribute.Availability]: () => this.evaluateAvailability(scenario, architecture),
      [QualityAttribute.Security]: () => this.evaluateSecurity(scenario, architecture),
      [QualityAttribute.Scalability]: () => this.evaluateScalability(scenario, architecture),
      [QualityAttribute.Maintainability]: () => this.evaluateMaintainability(scenario, architecture),
      [QualityAttribute.Testability]: () => this.evaluateTestability(scenario, architecture),
      [QualityAttribute.Deployability]: () => this.evaluateDeployability(scenario, architecture),
      [QualityAttribute.Observability]: () => this.evaluateObservability(scenario, architecture),
    };

    return evaluators[scenario.attribute]();
  }

  private evaluatePerformance(scenario: QualityScenario, arch: ArchitectureSpec): EvaluationResult {
    const gaps: string[] = [];
    const recommendations: string[] = [];

    // Check caching layer
    if (!arch.components.some(c => c.type === 'cache')) {
      gaps.push('No caching layer defined');
      recommendations.push('Add Redis or Memcached for response caching');
    }

    // Check CDN for static assets
    if (!arch.components.some(c => c.type === 'cdn')) {
      gaps.push('No CDN for static content');
      recommendations.push('Consider CloudFront or Fastly for static assets');
    }

    // Check database indexing strategy
    const db = arch.components.find(c => c.type === 'database');
    if (db && !db.config?.indexingStrategy) {
      gaps.push('No database indexing strategy documented');
      recommendations.push('Document query patterns and indexing strategy');
    }

    return {
      scenario,
      status: gaps.length === 0 ? 'met' : gaps.length < 2 ? 'partially_met' : 'not_met',
      evidence: 'Architectural analysis of performance-related components',
      gaps,
      recommendations,
    };
  }

  private evaluateAvailability(scenario: QualityScenario, arch: ArchitectureSpec): EvaluationResult {
    const gaps: string[] = [];
    const recommendations: string[] = [];

    // Check for redundancy
    const services = arch.components.filter(c => c.type === 'service');
    for (const service of services) {
      if (!service.config?.replicas || service.config.replicas < 2) {
        gaps.push(`${service.name} has no redundancy`);
        recommendations.push(`Configure at least 2 replicas for ${service.name}`);
      }
    }

    // Check for health checks
    for (const service of services) {
      if (!service.config?.healthCheck) {
        gaps.push(`${service.name} has no health check`);
        recommendations.push(`Add liveness and readiness probes to ${service.name}`);
      }
    }

    // Check for database failover
    const db = arch.components.find(c => c.type === 'database');
    if (db && !db.config?.failover) {
      gaps.push('Database has no failover configuration');
      recommendations.push('Configure read replicas and automatic failover');
    }

    return {
      scenario,
      status: gaps.length === 0 ? 'met' : gaps.length < 3 ? 'partially_met' : 'not_met',
      evidence: 'Analysis of redundancy and failover configurations',
      gaps,
      recommendations,
    };
  }

  // Additional evaluators for other quality attributes...
}

Review Checklist Generator

// src/architecture/review-checklist.ts
interface ChecklistItem {
  category: string;
  item: string;
  description: string;
  required: boolean;
  status?: 'pass' | 'fail' | 'na' | 'pending';
  notes?: string;
}

export class ArchitectureReviewChecklist {
  static generate(reviewType: 'initial' | 'milestone' | 'pre-production'): ChecklistItem[] {
    const baseChecklist: ChecklistItem[] = [
      // Documentation
      { category: 'Documentation', item: 'C4 Context Diagram', description: 'System context showing external dependencies', required: true },
      { category: 'Documentation', item: 'C4 Container Diagram', description: 'High-level technology choices', required: true },
      { category: 'Documentation', item: 'C4 Component Diagram', description: 'Internal component structure', required: reviewType !== 'initial' },
      { category: 'Documentation', item: 'API Specifications', description: 'OpenAPI/GraphQL schemas', required: true },
      { category: 'Documentation', item: 'Data Model', description: 'Entity relationships and schemas', required: true },

      // Security
      { category: 'Security', item: 'Authentication Design', description: 'How users/services authenticate', required: true },
      { category: 'Security', item: 'Authorization Model', description: 'RBAC/ABAC implementation', required: true },
      { category: 'Security', item: 'Data Encryption', description: 'At-rest and in-transit encryption', required: true },
      { category: 'Security', item: 'Secrets Management', description: 'How secrets are stored and rotated', required: true },
      { category: 'Security', item: 'Security Audit', description: 'Third-party security review', required: reviewType === 'pre-production' },

      // Performance
      { category: 'Performance', item: 'Load Testing', description: 'Results from load testing', required: reviewType !== 'initial' },
      { category: 'Performance', item: 'Capacity Planning', description: 'Resource requirements and scaling', required: true },
      { category: 'Performance', item: 'Caching Strategy', description: 'Caching layers and invalidation', required: true },

      // Reliability
      { category: 'Reliability', item: 'Failure Modes', description: 'Documented failure scenarios', required: true },
      { category: 'Reliability', item: 'Disaster Recovery', description: 'DR plan and RTO/RPO', required: reviewType === 'pre-production' },
      { category: 'Reliability', item: 'Circuit Breakers', description: 'Fault isolation mechanisms', required: true },

      // Operations
      { category: 'Operations', item: 'Monitoring', description: 'Metrics, logs, and traces', required: true },
      { category: 'Operations', item: 'Alerting', description: 'Alert definitions and escalation', required: reviewType !== 'initial' },
      { category: 'Operations', item: 'Runbooks', description: 'Operational procedures', required: reviewType === 'pre-production' },
      { category: 'Operations', item: 'Deployment Strategy', description: 'CI/CD and rollback procedures', required: true },
    ];

    return baseChecklist;
  }

  static score(checklist: ChecklistItem[]): {
    total: number;
    passed: number;
    failed: number;
    percentage: number;
    blockers: ChecklistItem[];
  } {
    const required = checklist.filter(i => i.required);
    const passed = checklist.filter(i => i.status === 'pass');
    const failed = required.filter(i => i.status === 'fail');

    return {
      total: checklist.length,
      passed: passed.length,
      failed: failed.length,
      percentage: (passed.length / checklist.length) * 100,
      blockers: failed,
    };
  }
}

Usage Examples

Conduct Architecture Review

Apply architect-review-methodology skill to perform initial architecture review for new microservices platform

Evaluate Quality Attributes

Apply architect-review-methodology skill to assess availability and performance quality attributes

Generate Review Checklist

Apply architect-review-methodology skill to create pre-production architecture review checklist

Success Output

When successful, this skill MUST output:

✅ SKILL COMPLETE: architect-review-methodology

Completed:
- [x] Review metadata documented
- [x] Quality attribute scenarios defined
- [x] Architecture analysis completed
- [x] Risk assessment documented
- [x] Trade-off analysis performed
- [x] Recommendations prioritized
- [x] Review verdict documented

Outputs:
- Architecture review document
- Risk assessment matrix
- Recommendations with priorities (P0/P1/P2)
- Review verdict with compliance score

Completion Checklist

Before marking this skill as complete, verify:

Failure Indicators

This skill has FAILED if:

❌ Review metadata incomplete or missing
❌ Quality scenarios lack measurable criteria
❌ Risk assessment missing mitigation strategies
❌ No architecture diagram provided
❌ Recommendations lack priority classification
❌ Trade-off analysis missing or incomplete
❌ Review verdict ambiguous or not actionable

When NOT to Use

Do NOT use this skill when:

Architecture is still in ideation phase (use system-architecture-design instead)
Reviewing code implementation details (use code-review-patterns instead)
Only need quick sanity check (use lightweight review)
Architecture decisions already finalized and deployed
Time-sensitive hotfix review (use rapid-review-protocol)
Non-technical stakeholder review needed (use architecture-presentation skill)

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Reviewing without quality scenarios	Subjective assessment	Define measurable quality attributes first
Skipping risk assessment	Hidden technical debt	Always include probability/impact matrix
Missing trade-off analysis	Unjustified decisions	Document alternatives with weighted factors
Generic recommendations	Not actionable	Prioritize P0/P1/P2 with specific steps
No architecture diagram	Communication gaps	Include C4 or equivalent visual
Ignoring business context	Misaligned priorities	Start with business drivers/constraints
Single reviewer bias	Blind spots	Include multiple perspectives

Principles

This skill embodies:

#5 Eliminate Ambiguity - Clear measurable criteria for quality attributes
#6 Clear, Understandable, Explainable - Structured review format with visual diagrams
#8 No Assumptions - Document constraints, risks, and trade-offs explicitly
#9 Based on Facts - Use ATAM-inspired quality evaluation methodology

Full Standard: CODITECT-STANDARD-AUTOMATION.md

Integration Points

system-architecture-design - Architecture documentation
adr-compliance - Decision record integration
code-review-patterns - Code-level architecture validation

When to Use This Skill​

How to Use This Skill​

Core Capabilities​

Architecture Review Framework​

Quality Attribute Evaluation​

Review Checklist Generator​

Usage Examples​

Conduct Architecture Review​

Evaluate Quality Attributes​

Generate Review Checklist​

Success Output​

Completion Checklist​

Failure Indicators​

When NOT to Use​

Anti-Patterns (Avoid)​

Principles​

Integration Points​