architecture-review

name	architecture-review
description	Review a proposed or implemented architecture against real product constraints, boundaries, dependency direction, data ownership, failure behavior, operability, security, migration, and unnecessary complexity.

Architecture Review

Use when an architecture proposal, ADR, cross-component design, or major implementation needs independent architectural scrutiny before commitment or release.

Procedure

1. Restate the actual problem, constraints, expected scale, reliability/security needs, team/runtime realities, and existing system context. Review against those forces, not against a generic ideal architecture.
2. Check component boundaries and ownership. Each major component should own coherent decisions/data and expose a contract that protects consumers from implementation details.
3. Review dependency direction and coupling: cycles, shared mutable state, shared databases, cross-layer imports, universal schemas, vendor/framework leakage, and components that must deploy/change together unexpectedly.
4. Review data/control flow end to end, including authority, consistency, caching, event ordering, retries, idempotency, and where durable state lives.
5. Review failure behavior at every boundary. Network/process boundaries introduce partial failure, timeout, retry, version mismatch, duplicate delivery, and observability requirements that local calls may not.
6. Review operability: configuration, deployment topology, health/readiness, upgrades, rollback/forward recovery, backup/restore, capacity, observability, and how an operator will diagnose the system under failure.
7. Review security and trust boundaries at the architectural level, then route detailed security validation to agency-security-engineer rather than substituting architecture review for security review.
8. Review migration and compatibility with current callers/data. A clean target diagram is incomplete if the system cannot reach it safely from the current state.
9. Challenge speculative complexity. Identify services, abstractions, queues, caches, plugin systems, generalized frameworks, or distributed protocols whose cost is not justified by a current constraint or credible near-term requirement.