| name | architect-review |
| description | Conduct a rigorous architecture review covering scope, drivers, quality attributes, risks, decisions, and action items. Use when a system, service, or major change needs an ATAM-lite review before commitment. |
| risk | unknown |
| source | community |
| date_added | 2026-02-27 |
Architecture Review (ATAM-lite)
A structured review surfaces risks before they become incidents. This skill drives a one-to-three day review producing a defensible record of drivers, decisions, sensitivities, trade-offs, and tracked actions aligned to ISO/IEC/IEEE 42010:2022 and ISO/IEC 25010:2023 quality models.
Stack Baseline (2026)
| Concern | Recommended |
|---|
| Quality model | ISO/IEC 25010:2023 (functional suitability, reliability, performance efficiency, security, maintainability, portability, compatibility, usability, safety) |
| Architecture description | ISO/IEC/IEEE 42010:2022 viewpoints + arc42 sections |
| Diagrams | C4 model (context, container, component) via Structurizr DSL or Mermaid |
| Decision log | MADR 4.x ADRs in /docs/adr |
| Evaluation method | ATAM-lite (utility tree + scenario walk-through) |
| Risk taxonomy | Risk / Sensitivity Point / Trade-off / Non-risk |
| Tech currency check | ThoughtWorks Tech Radar (latest volume) |
When to Use
- Before committing to a target architecture or large refactor.
- After a significant incident or scaling cliff.
- Quarterly governance review of a Tier-1 system.
- Pre-acquisition or third-party integration due diligence.
Prerequisites
- Stated business drivers and top 5 quality attribute scenarios.
- Current C4 context + container diagrams (or willingness to draft them).
- Access to runtime metrics: SLOs, error budgets, incident history.
- A named architecture owner and at least one stakeholder per concern (product, security, SRE).
Instructions
flowchart LR
A[Frame scope and drivers] --> B[Build utility tree]
B --> C[Walk scenarios against architecture]
C --> D[Classify risks, sensitivities, trade-offs]
D --> E[Record ADRs and actions]
E --> F[Publish review report]
- Frame the review. Confirm scope, stakeholders, in/out of scope systems, and the decision the review must inform.
- Capture drivers. List business goals, constraints (regulatory, budget, time), and assumptions. Tie each to a quality attribute from ISO/IEC 25010:2023.
- Build a utility tree. For each top quality attribute, refine to concrete scenarios with stimulus, environment, and measurable response. Prioritize by business value and architectural difficulty (H/M/L each).
- Walk scenarios. For every High-High scenario, trace the request through the C4 containers/components and record the architectural decisions invoked.
- Classify each finding as Risk, Sensitivity Point, Trade-off, or Non-risk. Aggregate Risks into Risk Themes.
- Capture decisions as MADR ADRs. New or revisited decisions get an ID, status, context, options, decision, and consequences.
- Produce the report using the Output Format below and assign owners + dates to every action.
ADR snippet (MADR 4.x):
# ADR-0042: Adopt outbox pattern for order events
Status: Accepted (2026-04-30)
Context: Dual-write between Postgres and Kafka risks lost events on partial failure.
Decision: Persist events to an outbox table; relay via Debezium CDC to Kafka.
Consequences: +Atomic with business txn; -Adds CDC operational surface; revisit when EventStoreDB is mature in our org.
Common Pitfalls
| Pitfall | Why it hurts | Mitigation |
|---|
| Reviewing diagrams without scenarios | Misses runtime risks | Drive review from utility tree scenarios |
| Treating every concern as a Risk | Dilutes signal | Use Risk/Sensitivity/Trade-off/Non-risk taxonomy |
| No measurable responses | Cannot verify later | Require numeric SLO/SLA in every scenario |
| Skipping ADR follow-up | Decisions drift | Every accepted recommendation lands as an ADR |
| Single-stakeholder view | Bias and blind spots | Include product, security, SRE, and on-call |
| Ignoring tech currency | Lock-in to fading stacks | Cross-check choices vs ThoughtWorks Tech Radar |
Output Format
# Architecture Review: <System> (<YYYY-MM-DD>)
## 1. Scope and Stakeholders
## 2. Business Drivers and Constraints
## 3. Quality Attribute Utility Tree (top scenarios, H/M/L x H/M/L)
## 4. Architecture Snapshot (C4 context + container links)
## 5. Scenario Walk-throughs
## 6. Findings
- Risk Themes (RT-1..n)
- Sensitivity Points
- Trade-offs
- Non-risks
## 7. Decisions (links to ADR-XXXX)
## 8. Action Items (owner, due date, exit criteria)
## 9. Open Questions
Authoritative References
- Mark Richards & Neal Ford, Fundamentals of Software Architecture, 2e (O'Reilly, 2025).
- Neal Ford, Mark Richards, Pramod Sadalage, Zhamak Dehghani, Software Architecture: The Hard Parts.
- Gregor Hohpe, The Software Architect Elevator.
- ISO/IEC/IEEE 42010:2022 — Architecture description.
- ISO/IEC 25010:2023 — Systems and software quality models.
- C4 model: https://c4model.com.
- arc42 template: https://arc42.org.
- ThoughtWorks Technology Radar: https://www.thoughtworks.com/radar.
