tech-architecture-review

name: tech-architecture-review description: > Technology architecture assessment across the "-ilities" -- scalability, reliability, maintainability, security, observability, performance, and extensibility. USE THIS SKILL when the user asks about architecture reviews, scalability assessments, tech debt quantification, system design evaluation, modernization planning, cloud architecture review, or infrastructure assessment. Includes system decomposition, failure mode analysis, technical debt classification, and remediation roadmap generation with prioritized investments.

Technology Architecture Review

Required Inputs

• System/Platform Name: What is being reviewed.
• Review Scope: Full architecture, specific subsystem, or specific concern (scalability, security, etc.).
• Business Context: Growth plans, performance requirements, regulatory constraints.
• Available Documentation: Architecture diagrams, runbooks, ADRs, monitoring dashboards.
• Access Level: Documentation only, read-only system access, or full environment access.
• Success Criteria: What "good" looks like for this organization (SLAs, growth targets, compliance).

Execution Steps

1. System Decomposition Analysis

Map the entire system before assessing individual qualities.

Component Inventory:

Dependency Mapping:

Dependency Risk Classification:

• Circular dependencies: Components with bidirectional synchronous calls (always Significant Risk)
• Critical chain length: Longest synchronous call chain (>4 hops = performance and reliability risk)
• Single points of failure: Components where failure cascades to >50% of system (Deal Breaker if no redundancy)
• External dependencies: Third-party services without fallback (risk proportional to SLA gap)

System Boundary Diagram Requirements:

• Data flow direction and volume (requests/sec, GB/day)
• Authentication and authorization boundaries
• Network boundaries (VPC, subnet, public/private)
• Data classification zones (public, internal, confidential, restricted)

2. Architecture Assessment: The "-ilities"

Score each dimension on the 1-5 maturity scale with specific evidence.

2a. Scalability Assessment

Scaling Model Analysis:

Capacity Planning Matrix:

Scalability Score Rubric:

2b. Reliability Assessment

SLA/SLO Evaluation:

Failure Mode Analysis:

Disaster Recovery Assessment:

Reliability Score Rubric:

2c. Maintainability Assessment

Onboarding Time Benchmark:

2d. Security Architecture Review

Defense in Depth Assessment:

Zero Trust Evaluation:

Threat Modeling (STRIDE per component):

2e. Observability Assessment

2f. Performance Assessment

Performance Analysis Methodology:

Performance Anti-Pattern Detection:

2g. Extensibility Assessment

3. Technical Debt Classification and Quantification

Technical Debt Inventory:

Category Definitions:

Technical Debt Quantification:

Remediation Cost = Effort (person-days) x Daily Rate
Carrying Cost = Weekly productivity impact (hours) x Hourly Rate x 52
Debt ROI = Annual Carrying Cost / Remediation Cost

Prioritize: Debt ROI > 2.0 = remediate immediately
            Debt ROI 1.0-2.0 = plan for next quarter
            Debt ROI < 1.0 = accept or defer

4. API Design and Integration Architecture Review

API Quality Assessment:

Integration Architecture Patterns:

5. Cloud Architecture Assessment

Well-Architected Framework Alignment:

Cloud Anti-Pattern Detection:

6. Modernization Pathway Options

Modernization Strategy Selection:

Modernization Decision Framework:

Urgency Interpretation:

• Score < 2.0: Maintain and incrementally improve
• Score 2.0-3.0: Plan modernization, start with highest-impact areas
• Score 3.0-4.0: Prioritize modernization; significant business risk from delay
• Score > 4.0: Urgent modernization required; allocate dedicated budget and team

7. Architecture Decision Records (ADR) Framework

ADR Template:

# ADR-[NNN]: [Decision Title]

**Status**: [Proposed / Accepted / Deprecated / Superseded]
**Date**: [YYYY-MM-DD]
**Decision Makers**: [Names and roles]

## Context
[What is the issue that we are seeing that motivates this decision?]

## Decision
[What is the change that we are proposing and/or doing?]

## Consequences
### Positive
- [Benefit 1]

### Negative
- [Trade-off 1]

### Risks
- [Risk with mitigation]

## Alternatives Considered
| Alternative | Pros | Cons | Reason Rejected |
|---|---|---|---|
| [Alt 1] | | | |

ADR Practice Assessment:

8. Remediation Roadmap

Prioritized Investment Framework:

Plot all findings on Impact (business value of fixing) vs. Effort (cost to fix):

Remediation Phasing:

Output Template

# Architecture Review: [System/Platform Name]

**Prepared for**: [Stakeholder] | **Date**: [Date] | **Scope**: [Full / Subsystem / Specific Concern]

## Executive Summary

**Overall Architecture Health**: [X.X] / 5.0 -- Level [N]: [Ad Hoc / Managed / Defined / Quantified / Optimizing]

[3-5 sentence summary: architecture strengths, critical gaps, and recommended
investment priorities. State whether the architecture supports projected business needs.]

### Architecture Scorecard
| Dimension | Score (1-5) | Status | Key Finding |
|---|---|---|---|
| Scalability | X.X | [Severity] | [One-line finding] |
| Reliability | X.X | [Severity] | [One-line finding] |
| Maintainability | X.X | [Severity] | [One-line finding] |
| Security | X.X | [Severity] | [One-line finding] |
| Observability | X.X | [Severity] | [One-line finding] |
| Performance | X.X | [Severity] | [One-line finding] |
| Extensibility | X.X | [Severity] | [One-line finding] |
| **Overall** | **X.X** | | |

### Finding Summary
| Severity | Count | Key Items |
|---|---|---|
| Deal Breaker | X | [Brief descriptions] |
| Significant Risk | X | [Brief descriptions] |
| Manageable | X | [Brief descriptions] |
| Non-Issue | X | -- |

### Estimated Remediation Investment: $[X]M - $[Y]M (18 months)

## 1. System Decomposition
**Total Components**: [X] | **Critical Dependencies**: [X] | **Single Points of Failure**: [X]
[Component inventory and dependency map]

## 2. Scalability Assessment
**Current Headroom**: [X]x before bottleneck
**Scaling Model**: [Vertical / Horizontal / Auto / Mixed]
[Capacity analysis and bottleneck identification]

## 3. Reliability Assessment
**Achieved Uptime**: [99.X%] vs. Target [99.X%]
**RPO**: [X] | **RTO**: [X] | **Last DR Test**: [Date]
[Failure mode analysis, DR assessment]

## 4. Security Architecture
**Defense in Depth Score**: [X.X]/5.0
**Zero Trust Maturity**: [X.X]/5.0
[Threat model findings, compliance gaps]

## 5. Maintainability & Technical Debt
**Tech Debt Ratio**: [X]% | **Estimated Remediation**: $[X]M
[Debt inventory, prioritized remediation]

## 6. Observability
**Observability Score**: [X.X]/5.0
[Gaps in logging, metrics, tracing, alerting]

## 7. Performance
**P95 Response Time**: [X]ms vs. Target [X]ms
[Performance analysis, anti-patterns identified]

## 8. Cloud Architecture
**Well-Architected Alignment**: [X.X]/5.0
[Anti-patterns identified, optimization opportunities]

## 9. Modernization Assessment
**Modernization Urgency**: [X.X]/5.0
**Recommended Strategy**: [Strangler Fig / Incremental / Platform Migration / Encapsulate]
[Modernization pathway with rationale]

## Technical Debt Register

| ID | Debt Item | Category | Impact | Effort | Debt ROI | Priority |
|---|---|---|---|---|---|---|
| TD-001 | [Description] | [Category] | [1-5] | [Person-days] | [X.X] | [Immediate/Q+1/Defer] |

## Remediation Roadmap

### Phase 1: Stabilize (Months 1-3) -- Budget: $[X]
| Initiative | Finding | Effort | Cost | Expected Outcome |
|---|---|---|---|---|
| [Initiative] | [Ref #] | [Person-weeks] | $[X] | [Measurable outcome] |

### Phase 2: Strengthen (Months 3-9) -- Budget: $[X]
| Initiative | Finding | Effort | Cost | Expected Outcome |
|---|---|---|---|---|

### Phase 3: Scale (Months 9-18) -- Budget: $[X]
| Initiative | Finding | Effort | Cost | Expected Outcome |
|---|---|---|---|---|

## Architecture Decision Recommendations

### ADR-001: [Decision Title]
**Recommendation**: [Proposed change]
**Rationale**: [Why this decision, what alternatives were considered]
**Trade-offs**: [What we give up]

## Appendix
- Component inventory (full)
- Dependency map (diagram)
- Performance test results
- Security scan results

Quality Checks

• All seven "-ilities" assessed with individual scores and evidence.
• System decomposition includes component inventory and dependency mapping.
• Scalability assessed at 2x, 5x, and 10x current load with bottleneck identification.
• Reliability analysis includes SLA/SLO evaluation, failure modes, and DR assessment.
• Security review covers defense in depth, zero trust, and threat modeling (STRIDE).
• Technical debt classified by category and type, quantified in dollar terms.
• Debt ROI calculated to prioritize remediation investments.
• API and integration architecture reviewed with pattern recommendations.
• Cloud architecture assessed against well-architected framework.
• Performance anti-patterns identified with specific remediation guidance.
• Modernization pathway recommended with decision framework scoring.
• ADR framework provided for ongoing architecture governance.
• Remediation roadmap phased (Stabilize / Strengthen / Scale) with budget allocation.
• All findings classified as Deal Breaker / Significant Risk / Manageable / Non-Issue.
• Technology maturity model (1-5) applied consistently across all dimensions.
• Cost estimates provided as ranges with confidence levels.