Purpose
Turn an architecture proposal into a structured review that surfaces the failure modes, hidden costs, and unstated assumptions a design doc usually hides — then delivers a clear build / revise / reject recommendation with severity-ranked findings, so review meetings are decisions instead of open-ended discussions.
When to Use
Invoke this skill when the user asks to:
- Review an architecture proposal, RFC, or system design document
- Evaluate whether a proposed design is ready to build
- Prepare feedback ahead of a design review meeting
- Compare a design against scalability, reliability, or consistency requirements
- Pressure-test a design for failure modes before committing engineering time
- Standardize architecture review feedback across multiple teams
Inputs Required
Before starting, collect:
- Design document: The proposal, RFC, or design doc text (or a summary of the proposed architecture)
- Problem being solved: What business/product need drives this design
- Scale targets: Expected load — requests/sec, data volume, user count, growth rate
- SLA / reliability targets: Uptime target, acceptable latency, RTO/RPO if known
- Consistency requirements: Does the data need strong consistency, or is eventual acceptable, and where
- Constraints: Team size, timeline, existing stack, budget, compliance requirements
- Stage: Early exploration / near-final proposal / already partially built
If scale targets or SLAs are missing, ask one clarifying question before reviewing — a design cannot be evaluated without knowing what it must survive. If constraints are missing, assume a small-to-mid-size team on an existing cloud stack and note the assumption.
Instructions
Step 1: Restate the Design and Its Assumptions
Before critiquing, prove you understand the proposal:
- Summarize the architecture in 3–5 sentences — the core components and how requests/data flow through them
- List the explicit assumptions the doc states (scale, consistency model, dependencies)
- List the implicit assumptions the doc relies on but never states (e.g., "assumes the database can handle write bursts," "assumes downstream service is always available")
- Flag any assumption that, if wrong, invalidates the design. These become priority review targets.
Step 2: Score Against the 8 Review Dimensions
For each dimension, assign a rating — Strong / Adequate / At Risk / Blocking — with concrete reasoning tied to the stated scale and SLA targets. Do not rate a dimension "Adequate" without naming what makes it adequate.
Dimension 1 — Scalability
- Identify the first bottleneck the design hits as load grows (usually the shared database, a synchronous call, or a single-writer path)
- Check whether scaling is horizontal (add nodes) or vertical (bigger box) and whether the design assumes the wrong one
- Verify the design handles the growth rate, not just current load — a design that works at 1x and breaks at 3x is At Risk if growth is expected
Dimension 2 — Reliability & Fault Tolerance
- For each external dependency, ask: what happens when it's slow, and what happens when it's down? Timeouts, retries, circuit breakers, fallbacks?
- Identify single points of failure — any component whose loss takes down the system
- Check for cascading failure risk (retry storms, unbounded queues, thundering herd)
- Verify the design can actually meet the stated SLA given its dependency chain (multiply availabilities of serial dependencies)
Dimension 3 — Data Consistency & Correctness
- Match the consistency model to the requirement — flag eventual consistency where strong is needed, and flag distributed transactions where they aren't
- Check for dual-write problems (writing to two stores without a single source of truth)
- Verify idempotency on any operation that can be retried
- Identify where the design relies on distributed coordination and whether that's justified
Dimension 4 — Observability
- Can an on-call engineer diagnose a failure at 3am with what this design emits? Check for metrics, structured logs, and distributed tracing across service boundaries
- Verify there are meaningful SLIs and that alerting is on symptoms (user-facing) not just causes
- Flag any critical path with no visibility
Dimension 5 — Security & Data Handling
- Check auth/authz boundaries between components — is trust assumed where it shouldn't be?
- Identify where sensitive data lives, how it's encrypted at rest and in transit, and blast radius if a component is compromised
- Flag compliance-relevant data flows (PII, PCI, PHI) if constraints indicate they apply
Dimension 6 — Cost
- Estimate the dominant cost drivers (data egress, high-cardinality storage, per-request compute, cross-region traffic)
- Flag designs whose cost scales super-linearly with usage
- Check whether cost was considered at all — "not addressed" is a valid finding
Dimension 7 — Operational Complexity
- Count the moving parts and ask whether the team size can operate them. A design that needs 5 new services for a 3-person team is At Risk regardless of technical elegance
- Check deployment, migration, and rollback story — can this be shipped incrementally?
- Flag new operational burdens (a new datastore to run, a new queue to monitor)
Dimension 8 — Evolvability
- Assess how hard it is to change this design in 12 months — are interfaces versioned, are couplings tight, is there a clear seam for the most likely future requirement?
- Flag premature abstraction (building for scale/flexibility that isn't needed) as strongly as under-engineering
- Identify one-way doors: decisions that are expensive to reverse
Step 3: Compile Severity-Ranked Findings
Consolidate all issues into a single ranked list. Assign each a severity:
- Blocking — must be resolved before building; the design fails a hard requirement or has an unacceptable failure mode
- Major — should be resolved; creates significant risk or cost but has workarounds
- Minor — worth addressing; won't sink the design
- Question — needs an answer from the author before it can be rated
For each finding: state the issue, the concrete consequence, and a specific suggested direction (not "consider scalability" — instead "the single Postgres writer caps you at ~X writes/sec; shard by tenant or introduce a write-ahead queue").
Step 4: Recommend a Decision
Make a clear call — do not hedge:
- Approve to build — no blocking findings; note any majors to track
- Approve with required changes — list the specific changes that must land before or during build
- Revise and re-review — there are blocking findings the author must resolve, then bring back
- Reject / rethink — the approach is wrong for the problem; explain what to reconsider
Step 5: Required Follow-Ups
List the specific artifacts or answers needed before or during implementation: load test plan, failure-injection test, capacity model, a specific ADR to write, a proof-of-concept for the riskiest assumption.
Output Format
- Structure: Design restatement → 8-dimension scorecard (as a table) → severity-ranked findings → decision → required follow-ups
- Length: 900–1,300 words
- Format: Structured document — the dimension scorecard as a table (Dimension | Rating | Key reasoning), findings as a ranked list with severity tags, decision as a single clear verdict
- Sections: Design & Assumptions / Dimension Scorecard / Ranked Findings / Decision / Required Follow-Ups
- Tone: Senior technical reviewer — direct, specific, decision-oriented. Critical without being dismissive; every criticism paired with a concrete direction.
Quality Checklist
Before delivering output, verify:
- [ ] All 8 dimensions are rated with reasoning tied to the stated scale and SLA targets — none rated on vibes
- [ ] At least one implicit (unstated) assumption is surfaced in the restatement
- [ ] Every finding has a severity tag, a concrete consequence, and a specific suggested direction
- [ ] Reliability analysis names actual failure modes (dependency down/slow, SPOF, cascade) — not generic "add redundancy"
- [ ] A single unambiguous decision is made from the four options — no "it depends" as the final answer
- [ ] Required follow-ups are specific artifacts or answers, not restated findings
Notes
- The highest-value output is usually the implicit assumptions surfaced in Step 1 — most design doc failures come from an unstated assumption that turns out false under load.
- Rate over-engineering as harshly as under-engineering. A design built for 100x scale on a 3-person team is a reliability risk because no one can operate it.
- When scale and SLA targets are both missing, the review is not possible — get them first. A design is only "good" relative to what it must survive.
- For early-stage proposals, weight Evolvability and Operational Complexity heavily; for near-final proposals, weight Reliability, Consistency, and Observability heavily.
How to use this skill
This file is a Claude Code skill in Anthropic's standard format — markdown with YAML frontmatter at the top.
Installing in Claude Code:
~/.claude/skills/<folder-name>/SKILL.md— auto-loads in every session anywhere on your machine (recommended for skills you'll use across multiple projects)<your-project>/.claude/skills/<folder-name>/SKILL.md— auto-loads only when working in that project (recommended for project-specific skills)
Restart Claude Code or open a new session to register.
Using in Claude.ai, ChatGPT, Gemini, or other AI tools:
- Drag this file into a new chat, or copy and paste its contents
- Send your task or request as your next message — the AI will apply the skill where it fits
For Claude Code skill details: https://docs.anthropic.com/en/docs/claude-code/skills