System Design Review

Review architectural decisions by walking the system through design lenses. Keep one question in view throughout the review:

"Was this a conscious decision, or an inherited default?"

Surface inherited defaults, underspecified decisions, explicit tradeoffs, cross-cutting tensions, and the sharpest next questions. Work at the architecture level, not the implementation-bug level.

Quick start

• Choose exactly one scope level: system, subsystem, or interface.
• Infer the top 1-2 system archetypes and state confidence.
• Propose a stakes tier before going deep. Never silently downgrade risk.
• Screen all 8 categories with sentinel questions before producing findings.
• Deep-dive only the lenses that earned attention through archetype weighting, screening signals, or cross-category linkage.
• End with sharp questions, not a verdict.

Defaults and failure modes

• If the user primarily wants incident reconstruction, debt prioritization, refactoring sequencing, implementation readiness, or code bug review, hand off immediately instead of forcing an architecture review.
• If the request mixes scope levels, ask which scope to review first.
• If multiple plausible review targets are in scope, name them and ask which one to review first. If the user does not choose, review the artifact they referenced most directly; if that is still tied, prefer the design doc for intended architecture and the codebase for implemented architecture. Do not blend multiple targets into one pass unless the user explicitly asks for both.
• If the input is sparse, mark categories insufficient evidence instead of guessing.
• If 4 or more categories would be insufficient evidence, say so explicitly, ask whether to narrow scope, and label the review reduced-depth if you continue without clarification.
• If no material findings surface at the chosen depth, say so directly. Do not pad the review.

Scope and handoffs

In scope: architectural diagnosis using the lens framework. Judge decision quality and system shape, not line-level implementation quality.

If the request mixes in-scope and out-of-scope work, perform the architecture diagnosis first, then state the handoff explicitly. Do not silently expand into adjacent workflows.

Execution flow

Frame -> Screen -> Deep Dive -> Deliver

1. Frame - choose scope, infer archetypes, calibrate stakes
2. Screen - build an evidence map and run sentinel questions across all 8 categories
3. Deep Dive - analyze the lenses that earned attention, then assemble findings and tensions
4. Deliver - present staged checkpoints appropriate to the stakes tier

1. Frame

Scope selection

Choose one scope level before starting. Do not mix scope levels in one run.

• system - the whole architecture at the top level
• subsystem - a bounded component or service
• interface - a specific boundary, contract, or integration point

If the user asks for both a system-level review and an interface deep dive, ask which one to review first.

Archetype identification

Infer the top 1-2 archetypes from the input. State them with a confidence level and proceed unless ambiguity would materially change which lenses deserve deep attention.

Available archetypes:

• Internal tool or back-office
• User-facing API or SaaS
• Data pipeline or ETL
• Financial or regulated
• ML or research platform
• Event-driven or streaming

When the system does not map cleanly to the list, infer up to 2 archetypes, reduce weighting strength if confidence is low, and fall back to unweighted screening plus evidence-promoted lenses if no archetype fits.

Example framing:

Archetype: User-facing API + event-driven (medium confidence)
If that's wrong, correct me now. It changes which lenses I prioritize.

Stakes calibration

Propose stakes and proceed. Stakes control depth, finding count, and when to invite correction.

• low - reversible, narrow blast radius, internal-only
• medium - meaningful blast radius or partial irreversibility
• high - hard to reverse, external or shared impact, or meaningful trust, safety, or reliability exposure

Use this decision order:

1. Honor an explicit user depth request unless a higher-risk cue overrides it.
2. If any high-risk cue is present, propose high.
3. If all cues are low-risk, propose low.
4. Otherwise, propose medium.
5. If uncertain between two tiers, choose the higher tier.

High-risk cues:

• External user-facing API
• Auth, permissions, or trust boundary
• Payments, regulated data, or sensitive data handling
• Migration or irreversible data change
• SLO, SLA, or availability commitment
• Shared platform or infrastructure
• Multi-team blast radius
• Distributed consistency concerns

Fail-safe: never silently downgrade. If the user does not answer a stakes question, proceed at the higher plausible tier.

2. Screen

Build an evidence map from the input, then run one sentinel question per category.

Sentinel questions

Category statuses

A category qualifies as screened only when all of these hold:

1. At least one concrete anchor exists.
2. The sentinel is answered in one sentence tied to that anchor.
3. The answer does not rely on guessing.

Promote screened to deep when the category is primary or secondary for the archetype, the sentinel surfaced a concern, or it connects to a finding from another category.

Evidence bars by input type

Design doc

• Read the full document first.
• Treat sections, diagrams, tables, and named decisions as anchors.
• Require 1 anchored sentinel answer for screened.

Codebase

• Build a bounded architecture sample with at most 12 anchors total:
  • 2 entrypoints
  • 2 orchestration or control-flow anchors
  • 2 data or state anchors
  • 2 boundary anchors such as API, queue, or adapter
  • 2 config, deploy, or observability anchors
  • 2 test or validation anchors
• Require 1 primary and 1 corroborating anchor for screened.
• If the codebase is too large, ask to narrow scope or mark more categories insufficient evidence.

Verbal description

• Use only explicit user statements as anchors.
• Require a direct quoted claim or clearly stated mechanism for screened.
• If the signal is only implied, mark insufficient evidence.

After screening, record one line per category with: status, sentinel used, anchor, and one-line disposition.

Global evidence floor

If 4 or more categories would be insufficient evidence, state this explicitly after screening and ask whether to continue at reduced depth or narrow scope before producing findings.

If the user does not respond, continue with a partial review limited to categories that cleared screening. Label the review reduced-depth in the snapshot and cap findings at 4.

Deep lens selection

After screening, select 6-10 individual lenses for the deep dive. For narrow interface scope or sparse verbal input, 4-6 is acceptable if you state why fewer lenses were genuinely relevant.

Select lenses in this order:

1. Archetype weighting from the bundled reference
2. Screening promotion where sentinel answers surfaced a real concern
3. Cross-category links where one concern explains another

If no archetype fits cleanly, skip step 1 and rely on evidence-promoted lenses only.

3. Deep dive

Analyze only the selected deep lenses. Produce findings and optional tensions, then assemble the review.

Output structure

Use 5 parts. Every section must earn its place. If a section has nothing meaningful, say so instead of padding it.

1. Review Snapshot

Use a compact table:

| Signal | Count |
| ------ | ----- |
| High-priority findings | N |
| Total findings | N |
| Tensions identified | N |
| Categories screened only | N |
| Insufficient evidence | N |

2. Focus and Coverage

State:

• scope level
• input type
• archetype or archetypes plus confidence
• stakes tier
• named deep lenses
• one-line status per category with status, sentinel, anchor, and disposition

3. Findings

Use labels F1, F2, and so on. Each finding must include:

• Lens
• Decision state
• Anchor
• Problem
• Impact
• Recommendation or question

4. Tension Map

Use labels T1, T2, and so on only when a real tension exists. Each tension must include:

• Tension
• What is being traded
• Why it hid
• Likely failure story
• Linked findings

5. Questions / Next Probes

End with 2-4 sharp questions. Do not end with a verdict unless the user explicitly asked for one.

Decision state taxonomy

Use default likely inherited only with positive evidence of a default. Lack of rationale alone is not enough. For codebase reviews, stay conservative: code shows what exists, not why.

Tension inclusion rules

Tensions are optional. 0 is a valid count. Do not force one.

Include a tension only when all of these hold:

1. Both sides have concrete anchors in the input.
2. You can explain the tradeoff mechanism.
3. You can explain why the tradeoff was easy to miss.
4. The tension explains at least 1 concrete finding.
5. The wording is specific to this system, not generic architecture prose.

Before emitting a tension, verify all 6 lines:

1. Side A anchor
2. Side B anchor
3. The decision or default that pulled toward side A
4. The cost or blind spot that appeared on side B
5. Why a reviewer could miss this
6. Which finding or findings this tension explains

Use the bundled tensions table as a prompt source, not a required menu. Custom tensions are valid.

Depth calibration

If you have more than 12 findings in the main reply, either cluster them by root cause or produce a saved artifact. Overflow findings, up to 15 total, go in a Deferred Findings appendix as one-line items with lens and decision state only.

No-findings path

If no material findings surface, say so directly. A clean review at the current depth is a valid outcome.

Delivery model

Use staged checkpoints. The user can redirect between stages.

Delivery defaults:

• low stakes: collapse into one message
• medium stakes: use one message unless scope or archetype is ambiguous, then invite correction at C0
• high stakes: invite reaction at C0 if framing is uncertain, otherwise at C1

If the user does not respond, continue. Checkpoints are invitations, not gates.

Anti-patterns

Example

User: "Review the architecture of our notification service. It handles email, SMS, and push via a single queue."

Review Snapshot

Signal	Count
High-priority findings	2
Total findings	5
Tensions identified	1
Categories screened only	3
Insufficient evidence	1

F1. Single queue for heterogeneous delivery channels

• Lens: Failure Containment
• Decision state: default likely inherited
• Anchor: Queue configuration in notification-service/config.yaml
• Problem: SMS gateway timeouts block email delivery, so failure in one channel propagates to all channels.
• Impact: A slow SMS provider degrades every notification type.
• Recommendation: Evaluate per-channel queues or priority lanes.

T1. Simplicity vs. failure containment

• What is being traded: Single-queue simplicity vs. per-channel isolation
• Why it hid: The system started with email only. SMS and push were added later without revisiting the original queue decision.
• Likely failure story: An SMS provider has a 30-second timeout spike, the queue backs up, and users miss time-sensitive email.
• Linked findings: F1, F3

Questions

1. Was the single-queue design revisited when SMS was added, or was the email-era default simply carried forward?
2. What is the SLO for email delivery latency, and does the current design meet it during SMS degradation?

Durable record

• If the user asks to save the review, or the workspace already uses docs/audits/, write docs/audits/YYYY-MM-DD-<target-slug>.md.
• Otherwise, keep the review in the reply.

Reference

Read references/system-design-dimensions.md when you need:

• the full list of named lenses within a category
• the weighting table for archetype-driven deep-lens selection
• the cross-cutting tensions table as a prompt source
• details on a specific lens the user names

Do not read the reference during screening. Sentinel questions are sufficient for that stage.