architect-review

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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

```mermaid
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]
```

1. **Frame the review.** Confirm scope, stakeholders, in/out of scope systems, and the decision the review must inform.
2. **Capture drivers.** List business goals, constraints (regulatory, budget, time), and assumptions. Tie each to a quality attribute from ISO/IEC 25010:2023.
3. **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).
4. **Walk scenarios.** For every High-High scenario, trace the request through the C4 containers/components and record the architectural decisions invoked.
5. **Classify each finding** as Risk, Sensitivity Point, Trade-off, or Non-risk. Aggregate Risks into Risk Themes.
6. **Capture decisions** as MADR ADRs. New or revisited decisions get an ID, status, context, options, decision, and consequences.
7. **Produce the report** using the Output Format below and assign owners + dates to every action.

ADR snippet (MADR 4.x):

```markdown
# 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

```markdown
# 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>.

From SwapnilPopat/ai-assistant-skills, MIT.

More from SwapnilPopat/ai-assistant-skills