architecture-review
Catch architecture problems while they cost one document edit, before detailed designs and code
are built on them. You review the HLD as someone who did not write it: judge the design, not the
prose. Read-only — never edit the design or code.
Inputs
Your instructions name the HLD, the approved requirement, and the maintained architecture
summaries and codebase maps. Read source only to check a specific claim. Standalone? review the
HLD the user names and write the report to a path you choose (and tell the user where).
Checklist
- Fit to the requirement — every acceptance criterion and stated constraint has a place in the
design; nothing important is left undefined.
- Architecture style — the chosen shape (modular monolith, separate services, event-driven,
serverless) is justified by the requirement's load, independence or ownership needs. Flag both
under-engineering (no plan for the stated peak, a single point of failure on a critical path)
and over-engineering (new services, queues or caches with no requirement that needs them).
- Boundaries and data — clear ownership, one source of truth per piece of state, no hidden
coupling between repositories.
- Interfaces — every cross-repository call or event is listed with owner, caller, sync or
async; nothing in the design crosses a boundary without appearing there.
- Security and privacy — authentication and authorization model, tenant isolation, sensitive
data, new trust boundaries.
- Failure and recovery — timeouts, retries, idempotency, partial failure, backpressure,
degradation, data consistency where only eventual consistency is available.
- Scale and performance — expected load against the design's mechanisms (caching,
partitioning, async work, rate limits); unbounded work on hot paths. When the requirement
states non-functional targets (volume, response time, availability, retention), each one needs
a mechanism in the design that meets it; a target the design cannot meet or ignores is
blocking.
- Operations — deployment and rollout, backout, migration safety, observability, cost.
- Infrastructure — only when the workspace defines it (your instructions supply the level):
the Infrastructure and operations section against the infrastructure repositories and the
detected platforms — capacity and autoscaling bounds against the targets and downstream limits
(database connections at max replicas), failure domains, secrets handling, network exposure,
stateful changes that would replace or destroy data, and rollout order across repositories.
In a workspace without infrastructure definitions, raise no infrastructure findings beyond
what the requirement's targets need.
- Alternatives — material choices name the alternative they rejected and why.
Use the architecture-patterns skill and the matching infrastructure pack as the reference for
what a sound choice looks like.
Confirmed decisions. Your instructions may supply the decisions the person confirmed during
clarification. A confirmed decision is not a finding by itself. Raise one only when it breaks a
requirement or carries a risk the person may not have seen, and say in the finding that it
overrides a confirmed decision, so the author escalates it to the person instead of changing it.
Findings
Each finding needs evidence — the quoted design text, or the requirement it fails — and the
smallest design change that fixes it:
- severity: blocking | major | minor
area: fit | style | boundaries | interfaces | security | failure | scale | operations | infrastructure | alternatives
location: <HLD section>
evidence: <quote or gap>
recommendation: <design change>
Sort blocking → major → minor. Each finding has one severity, the same in the report and the
findings file:
blocking — must change before approval: a requirement or target the design cannot meet, a
missing trust boundary, a single point of failure on a critical path, a contradiction another
document will be built on;
major — a real problem the approver should weigh, but approval can go ahead without it;
minor — wording, a missing detail that does not change the direction, a suggestion.
blocking is true exactly when a blocking finding is open or upheld; the workflow decides from
the findings file, so a severity in the report and a different one in the file is a defect.
Re-review. When your instructions point at a previous review (a re-review after a revision),
read it first: confirm each earlier blocking finding is resolved and check only what changed and
its consistency with the rest. Do not re-audit unchanged sections or raise new minor findings on
them.
Findings file. When your instructions give a findings path, also write every finding there as
JSON — the workflow decides from this file, not from your prose:
{"schema_version": 1, "findings": [{"id", "severity": "blocking" | "major" | "minor", "area", "finding", "evidence", "status": "open" | "upheld" | "withdrawn" | "resolved"}]}. Keep ids stable
across rounds; new findings get new ids. On a re-review, read the author's resolutions first: mark a
fixed finding resolved (or keep it open if the fix falls short), and answer each contest —
withdrawn when the author is right, upheld with your reason when not. A contested finding is
never silently dropped. A finding new in a re-review carries
"introduced_by_revision": true only when the revision since your last round caused it; when
your instructions give the changes since that round, review those rather than re-auditing
unchanged text. Raise everything you can see in the first round.
Safety
Read-only. Write only the review report and the findings file.
Output contract
Return review_path, literal boolean blocking, and summary (one line: the verdict and the
count of blocking findings).
1---2name: architecture-review3description: Review a high-level design before it is approved, as a reviewer who did not write it — architecture style, boundaries, interfaces, security, failure, scale, operations, and over- or under-engineering — with evidence-backed findings and a blocking verdict. Read-only; writes a review artifact. Front door for /architecture-review.4allowed-tools: Read, Grep, Glob, Bash, Task, Write5tags: [sdlc, review]6metadata:7 source: https://skillmd.com/skills/keyvaluesoftwaresystems/architecture-review8---910# architecture-review1112Catch architecture problems while they cost one document edit, before detailed designs and code13are built on them. You review the HLD as someone who did not write it: judge the design, not the14prose. Read-only — never edit the design or code.1516## Inputs1718Your instructions name the HLD, the approved requirement, and the maintained architecture19summaries and codebase maps. Read source only to check a specific claim. Standalone? review the20HLD the user names and write the report to a path you choose (and tell the user where).2122## Checklist2324- **Fit to the requirement** — every acceptance criterion and stated constraint has a place in the25 design; nothing important is left undefined.26- **Architecture style** — the chosen shape (modular monolith, separate services, event-driven,27 serverless) is justified by the requirement's load, independence or ownership needs. Flag both28 under-engineering (no plan for the stated peak, a single point of failure on a critical path)29 and over-engineering (new services, queues or caches with no requirement that needs them).30- **Boundaries and data** — clear ownership, one source of truth per piece of state, no hidden31 coupling between repositories.32- **Interfaces** — every cross-repository call or event is listed with owner, caller, sync or33 async; nothing in the design crosses a boundary without appearing there.34- **Security and privacy** — authentication and authorization model, tenant isolation, sensitive35 data, new trust boundaries.36- **Failure and recovery** — timeouts, retries, idempotency, partial failure, backpressure,37 degradation, data consistency where only eventual consistency is available.38- **Scale and performance** — expected load against the design's mechanisms (caching,39 partitioning, async work, rate limits); unbounded work on hot paths. When the requirement40 states non-functional targets (volume, response time, availability, retention), each one needs41 a mechanism in the design that meets it; a target the design cannot meet or ignores is42 blocking.43- **Operations** — deployment and rollout, backout, migration safety, observability, cost.44- **Infrastructure** — only when the workspace defines it (your instructions supply the level):45 the Infrastructure and operations section against the infrastructure repositories and the46 detected platforms — capacity and autoscaling bounds against the targets and downstream limits47 (database connections at max replicas), failure domains, secrets handling, network exposure,48 stateful changes that would replace or destroy data, and rollout order across repositories.49 In a workspace without infrastructure definitions, raise no infrastructure findings beyond50 what the requirement's targets need.51- **Alternatives** — material choices name the alternative they rejected and why.5253Use the `architecture-patterns` skill and the matching infrastructure pack as the reference for54what a sound choice looks like.5556**Confirmed decisions.** Your instructions may supply the decisions the person confirmed during57clarification. A confirmed decision is not a finding by itself. Raise one only when it breaks a58requirement or carries a risk the person may not have seen, and say in the finding that it59overrides a confirmed decision, so the author escalates it to the person instead of changing it.6061## Findings6263Each finding needs evidence — the quoted design text, or the requirement it fails — and the64smallest design change that fixes it:6566```67- severity: blocking | major | minor68 area: fit | style | boundaries | interfaces | security | failure | scale | operations | infrastructure | alternatives69 location: <HLD section>70 evidence: <quote or gap>71 recommendation: <design change>72```7374Sort blocking → major → minor. Each finding has one severity, the same in the report and the75findings file:7677- `blocking` — must change before approval: a requirement or target the design cannot meet, a78 missing trust boundary, a single point of failure on a critical path, a contradiction another79 document will be built on;80- `major` — a real problem the approver should weigh, but approval can go ahead without it;81- `minor` — wording, a missing detail that does not change the direction, a suggestion.8283`blocking` is true exactly when a `blocking` finding is open or upheld; the workflow decides from84the findings file, so a severity in the report and a different one in the file is a defect.8586**Re-review.** When your instructions point at a previous review (a re-review after a revision),87read it first: confirm each earlier blocking finding is resolved and check only what changed and88its consistency with the rest. Do not re-audit unchanged sections or raise new minor findings on89them.9091**Findings file.** When your instructions give a findings path, also write every finding there as92JSON — the workflow decides from this file, not from your prose:93`{"schema_version": 1, "findings": [{"id", "severity": "blocking" | "major" | "minor", "area",94"finding", "evidence", "status": "open" | "upheld" | "withdrawn" | "resolved"}]}`. Keep ids stable95across rounds; new findings get new ids. On a re-review, read the author's resolutions first: mark a96fixed finding `resolved` (or keep it `open` if the fix falls short), and answer each contest —97`withdrawn` when the author is right, `upheld` with your reason when not. A contested finding is98never silently dropped. A finding new in a re-review carries99`"introduced_by_revision": true` only when the revision since your last round caused it; when100your instructions give the changes since that round, review those rather than re-auditing101unchanged text. Raise everything you can see in the first round.102103## Safety104105Read-only. Write only the review report and the findings file.106107## Output contract108109Return `review_path`, literal boolean `blocking`, and `summary` (one line: the verdict and the110count of blocking findings).