| name | system-design-review |
| description | Use for system design, architecture proposals, ADRs, service decomposition, scale planning, storage/queue/cache choices, reliability trade-offs, rollout plans, and design reviews. Do not use for small local code edits. |
System Design Review
Workflow
- Identify the design target: new system, new feature, migration, scale-up, reliability improvement, or architecture review.
- Separate confirmed requirements from assumptions. State assumptions that affect capacity, latency, consistency, cost, or rollout risk.
- Define the system boundary: users, clients, APIs, services, databases, queues, caches, workers, external dependencies, and deployment surfaces.
- Design the simplest architecture that satisfies the known requirements. Prefer existing platform patterns before introducing new infrastructure.
- Evaluate trade-offs explicitly: consistency, availability, latency, throughput, complexity, operability, security/privacy, and cost.
- Identify failure modes and operational controls before finalizing the design.
- Produce an implementation or migration plan only after the design boundary and risks are clear.
Design Checks
- Functional requirements: main workflows, edge cases, user-visible contracts, and out-of-scope behavior.
- Non-functional requirements: p95/p99 latency, throughput, data volume, availability, recovery, retention, and cost targets.
- API surface: request/response contracts, idempotency keys, pagination, status/error mapping, and compatibility.
- Data model: ownership, schema, indexes, lifecycle, consistency, backfill, retention, and privacy constraints.
- Storage choice: read/write pattern, transactions, query shape, scale path, backup/restore, and operational maturity.
- Queue/event design: producer/consumer ownership, ordering, duplicate delivery, retries, dead letters, replay, and schema evolution.
- Cache design: keying, invalidation, TTL, stampede protection, stale reads, and fallback behavior.
- Reliability: timeouts, retries, circuit breakers, backpressure, rate limits, bulkheads, graceful degradation, and recovery.
- Observability: logs, metrics, traces, dashboards, alerts, runbooks, SLOs, and correlation IDs.
- Security/privacy: auth/authz, tenant boundaries, PII, secrets, auditability, data minimization, and compliance constraints.
- Rollout: feature flags, shadow/canary, dual writes, migrations, rollback/mitigation, and compatibility window.
Anti-Patterns
- Do not invent scale requirements when none are stated; provide assumption ranges instead.
- Do not choose new infrastructure only because it is fashionable.
- Do not hide hard constraints behind vague phrases such as "eventually scalable" or "highly available".
- Do not ignore operational ownership, migration order, or rollback path.
- Do not optimize for theoretical peak scale before the common path is correct and observable.
Output
For design work, report:
- Requirements and assumptions.
- Proposed architecture and key components.
- Data/API/event contracts.
- Trade-offs and rejected alternatives.
- Failure modes and operational controls.
- Migration or rollout plan.
- Validation plan and open questions.
Use references/design-brief-template.md for design proposals, references/adr-template.md for architecture decision records, and references/capacity-planning.md when capacity assumptions matter.
