Architecture review
Find choices that could make a technical proposal wrong, unsafe, or impossible
to prove. Review the proposed behavior and tradeoffs, not the document's size
or format.
Use one fresh subagent that did not write the proposal. Give the reviewer the
complete context. Tell the reviewer to work directly without delegating. If
you are that reviewer, review directly. Stay read-only.
If fresh subagents are unavailable, stop and report that independent review is
blocked. Continue only if the user explicitly accepts a documented self-review.
Process
- Read the goal, proposal, repository instructions, relevant current code,
tests, schemas, configuration, and linked material. Treat claims about the
current system as unverified until code, tests, schemas, configuration,
infrastructure, or relevant runtime evidence supports them.
- State the problem, affected user, intended outcome, success measure, scope,
constraints, and main tradeoff. Report any that the proposal leaves unclear.
- Trace one real case from input to observable outcome. Include ownership,
validation, state changes, side effects, response timing, failure, retry,
cleanup, and what the user sees where they matter.
- Challenge the chosen design with the review focus below. Look for a simpler
choice that reaches the same outcome and proof with less state, coupling,
duplication, or operational work.
- Surface material open questions. Recommend an answer when evidence supports
one. Do not invent questions that cannot change the design.
- Return findings, open questions, a short assessment, and one verdict.
Do not rewrite the proposal, plan the work, review implementation code, or
implement changes.
Review focus
- Check fit with the current system, ownership, boundaries, interfaces, data,
compatibility, migration, rollout, and rollback.
- Trace partial failure, retry, cancellation, concurrency, startup, shutdown,
and recovery where they affect the proposal.
- Check claimed scale, limited resources, latency, throughput, storage, cost,
dependency failure, and operator recovery only where they can change the choice.
- Check identity, authorization, untrusted input, credentials, destructive
authority, and sensitive data handling.
- Require observable acceptance criteria and proof for important rules and
failure paths. Do not let implementation invent user-visible behavior,
interfaces, data rules, security policy, or failure behavior.
Material questions
Report an open question only when two capable implementations could answer it
differently in a way that affects users, data, interfaces, security, scale,
performance, operations, cost, compatibility, or proof.
- Blocking: implementation should not start without the answer.
- Important: the proposal should record the answer, but the reviewer can
recommend a safe default from available evidence.
Omit questions that are stylistic, safely local to implementation, outside the
stated scope, or speculative beyond the scale the proposal claims to support.
Findings
Report only flaws that can change the design or its safety:
- Blocker: the choice is unsafe, contradicts the goal or current system, or
cannot recover from an important failure.
- Important: the proposal permits materially different implementations or
leaves a meaningful risk in behavior, scale, performance, security,
operations, compatibility, or proof.
For each finding or open question include its location, concrete failure or
ambiguity, impact, evidence, and the smallest correction or recommended answer.
Report unclear wording when it prevents a new teammate from explaining,
evaluating, or implementing the design. Omit other writing preferences.
Use plain words. State the exact condition, failure, and effect. Do not hide an
unknown behind vague language such as may have issues or could be risky.
Verdict
Approve: no blocker or important findings or open questions remain.
Request changes: the proposal has a fixable blocker or important finding or
open question.
Blocked: the review lacks required context, repository evidence, specialist
coverage, or an independent reviewer.
State what remains unverified. Do not approve because the document is detailed
or because every template section exists.
1---
2name: architecture-review
3description: "Reviews a technical proposal before implementation. Use for designs, RFCs, ADRs, architecture proposals, and issues that define how a system change should work. Finds material ambiguity and flaws in correctness, scalability, performance, security, operations, and proof."
4user-invocable: true
5argument-hint: "[technical proposal, design, RFC, ADR, or issue]"
6metadata:
7 source: https://skillmd.com/skills/owainlewis/architecture-review
8---
9
10# Architecture review
11
12Find choices that could make a technical proposal wrong, unsafe, or impossible
13to prove. Review the proposed behavior and tradeoffs, not the document's size
14or format.
15
16Use one fresh subagent that did not write the proposal. Give the reviewer the
17complete context. Tell the reviewer to work directly without delegating. If
18you are that reviewer, review directly. Stay read-only.
19
20If fresh subagents are unavailable, stop and report that independent review is
21blocked. Continue only if the user explicitly accepts a documented self-review.
22
23## Process
24
251. Read the goal, proposal, repository instructions, relevant current code,
26 tests, schemas, configuration, and linked material. Treat claims about the
27 current system as unverified until code, tests, schemas, configuration,
28 infrastructure, or relevant runtime evidence supports them.
292. State the problem, affected user, intended outcome, success measure, scope,
30 constraints, and main tradeoff. Report any that the proposal leaves unclear.
313. Trace one real case from input to observable outcome. Include ownership,
32 validation, state changes, side effects, response timing, failure, retry,
33 cleanup, and what the user sees where they matter.
344. Challenge the chosen design with the review focus below. Look for a simpler
35 choice that reaches the same outcome and proof with less state, coupling,
36 duplication, or operational work.
375. Surface material open questions. Recommend an answer when evidence supports
38 one. Do not invent questions that cannot change the design.
396. Return findings, open questions, a short assessment, and one verdict.
40 Do not rewrite the proposal, plan the work, review implementation code, or
41 implement changes.
42
43## Review focus
44
45- Check fit with the current system, ownership, boundaries, interfaces, data,
46 compatibility, migration, rollout, and rollback.
47- Trace partial failure, retry, cancellation, concurrency, startup, shutdown,
48 and recovery where they affect the proposal.
49- Check claimed scale, limited resources, latency, throughput, storage, cost,
50 dependency failure, and operator recovery only where they can change the choice.
51- Check identity, authorization, untrusted input, credentials, destructive
52 authority, and sensitive data handling.
53- Require observable acceptance criteria and proof for important rules and
54 failure paths. Do not let implementation invent user-visible behavior,
55 interfaces, data rules, security policy, or failure behavior.
56
57## Material questions
58
59Report an open question only when two capable implementations could answer it
60differently in a way that affects users, data, interfaces, security, scale,
61performance, operations, cost, compatibility, or proof.
62
63- **Blocking:** implementation should not start without the answer.
64- **Important:** the proposal should record the answer, but the reviewer can
65 recommend a safe default from available evidence.
66
67Omit questions that are stylistic, safely local to implementation, outside the
68stated scope, or speculative beyond the scale the proposal claims to support.
69
70## Findings
71
72Report only flaws that can change the design or its safety:
73
74- **Blocker:** the choice is unsafe, contradicts the goal or current system, or
75 cannot recover from an important failure.
76- **Important:** the proposal permits materially different implementations or
77 leaves a meaningful risk in behavior, scale, performance, security,
78 operations, compatibility, or proof.
79
80For each finding or open question include its location, concrete failure or
81ambiguity, impact, evidence, and the smallest correction or recommended answer.
82Report unclear wording when it prevents a new teammate from explaining,
83evaluating, or implementing the design. Omit other writing preferences.
84
85Use plain words. State the exact condition, failure, and effect. Do not hide an
86unknown behind vague language such as `may have issues` or `could be risky`.
87
88## Verdict
89
90- `Approve`: no blocker or important findings or open questions remain.
91- `Request changes`: the proposal has a fixable blocker or important finding or
92 open question.
93- `Blocked`: the review lacks required context, repository evidence, specialist
94 coverage, or an independent reviewer.
95
96State what remains unverified. Do not approve because the document is detailed
97or because every template section exists.