/system-design-review

name: system-design-review
description: "Audit an existing or proposed architecture and return a scored verdict across nine axes, from requirements and capacity evidence to observability and rollout, then convert gaps into a prioritized roadmap. Use when reviewing a design doc, auditing a running system, or gating a design."
metadata:
  triggers:
    keywords:
      - design review
      - architecture review
      - design scorecard
      - bottleneck analysis
      - scalability audit
      - evolution roadmap
      - architecture assessment

System Design Review

**Priority: P1 (HIGH)**

Score claims against evidence appropriate to the declared review scope. A proposed design may support a design-readiness verdict through stated mechanisms and planned validation; it cannot claim operational readiness from plans alone. An implementation review requires implementation evidence; an operations claim requires production runtime/deployment evidence.

Nine Axes (score each applicable axis 0-10)

| Axis | Scores 10 when | Scores 0 when | | --- | --- | --- | | Requirements | Functional, NFR, and out-of-scope written with owners | Only a feature description exists | | Capacity evidence | Peak QPS, storage, and bandwidth computed and current | Numbers absent or older than the last traffic change | | Redundancy | Failure domains, recovery mechanisms and ownership fit the stated objective; proposals include validation criteria, operations claims require measured drills when recovery is in scope | Critical SPOF or no viable recovery for the stated objective | | Data scaling | Access patterns mapped, ownership single, growth path stated; query amplification diagnosed via canonical database-query-performance; copies/authority checked | One shared store, no growth plan, unbounded tables, or an unmitigated amplification/copy risk | | Caching | Hot read paths cached with TTL and invalidation defined | No cache on a proven hot path, or uninvalidatable cache | | Async offload | Slow/bursty work is isolated when required by stated SLO or failure constraints, with bounded drain/recovery; bounded synchronous work is valid when it meets them | Required isolation is absent or synchronous coupling violates the stated constraints | | Observability | Journey indicators, signal/alert ownership, runbooks and validation fit declared scope; operations claims require observed SLO/telemetry | No relevant journey signals, owner or response path for a material risk | | Rollout | Canary or flag with metric rollback trigger and reversible migrations | Big-bang deploy, irreversible migration | | Cost proportionality | Spend is sized to the traffic and the risk, and someone can state it | Topology bought for an imagined scale nobody measured |

Non-Compensable Flow Gates

Apply gates to material risks in the declared scope, independent of the aggregate score. A failed gate blocks a sound verdict/readiness claim; points on unrelated axes cannot compensate. Report the evidence, user consequence, owner, adverse timeline, smallest corrective action, and trace to the violated invariant. A justified `N/A` applies only when that concern is genuinely outside the declared flow/risk scope and records why.

• **Correctness:** lost, duplicated, reordered, or stale effects violate the user/business invariant; missing acknowledgment/reconciliation leaves the outcome unknown without a safe resolution.
• **Tenant authorization:** a flow crosses or exposes tenant data without enforcement at the relevant trust boundary.
• **Sensitive data and deletion:** sensitive data is mishandled, or a deletion/retention promise fails across authoritative and derived copies, including replay or offline sync.
• **Migration:** a backfill, CDC, cutover, rollback, or restore can lose or overwrite authoritative data, or exposes unverified state as current.
• **Recoverability:** material data loss/downtime has no viable in-scope recovery mechanism or the claimed recovery outcome is unsupported at the declared lifecycle scope.

These gates do not require every proposal to prove deployment or operations. Proposals need sufficient mechanisms, assumptions, and planned checks for design readiness; implementation and operations claims require their corresponding evidence.

Report each applicable axis with evidence and a declared profile weighting. Use an applicable-axis denominator (`10 × applicable-axis count`), not a fixed `/90`, when an axis is justified `N/A`.

Profile-Aware Scoring

• Declare the system profile and weighting before scoring. An axis may be `N/A` only when the profile and evidence show that it is outside the system's risk envelope; record the rationale, exclude it from the denominator, and do not silently convert it to zero.
• Do not reward adding a cache, queue, replica, or region by vocabulary alone. A component earns credit only when a measured constraint, invariant, owner, cost, and failure/recovery behavior require it; unjustified machinery lowers cost proportionality and operability.
• Review HLD and LLD as one trace: requirements and shaping decisions must resolve into component ownership, contracts, verification, and a stated changed-constraint trigger. A diagram is optional when prose answers the question.
• Separate lifecycle (`proposed|implemented|retired`), source kind (`code|document|runtime|deployment`), and evidence confidence (`unverified|assumed|documented|observed`). Code/document citations are `documented`, not deployment proof; runtime/deployment captures may be `observed`. `assumed` and `unverified` carry no citation; explicit citations require `evidence_kind`.

Scope-Qualified Semantic Review

Lexical checks are smoke signals, not proof of a sound design. Apply the independent behavioral rubric in [semantic evaluation](references/semantic-evaluation.md). Record missing calculations, mechanisms, adverse timelines, invariants, recovery, and scope-specific evidence as findings even when expected vocabular