Reviewing Architecture Doc

reviewing-architecture-doc — SKILL.md

> Variant: standard · When to use: judging a finished whole-system architecture document (+ its linked ADR files) as an acceptance gate — checking an engineer can grasp the system and a feature's technical-design can place itself within it, then emitting VERDICT: approve|revise with actionable findings. Greenfield, or an amend (delta-scoped).

Overview

This skill is the review half of a producing/judging architecture-doc pair. Loaded by a reviewer who holds a finished whole-system architecture document + its linked ADR files, it judges them against one question: **can a new engineer grasp the system's structure and the why of its major decisions, and can a feature's technical-design locate itself within the architecture, without asking the author? It applies a fixed 10-condition architecture-quality checklist (the same bar an architecture-doc author produces to — authoring-architecture-doc's Step-7 — so the produce-bar and the review-bar do not drift), then emits a single machine-parseable verdict plus findings the author can act on in one revision pass. It is an acceptance gate — it does not** author, fix, or rewrite the doc; it judges and returns findings, and the producer revises.

It judges TWO artifacts: the architecture doc AND its linked ADR files. Condition 4 (the ADR mechanism — index⇄files sync + per-ADR quality + no-rewrite) is unverifiable from the doc alone — the reviewer needs the linked ADR files (or the adr/ directory). If they were not handed in, flag cond-4 as unverifiable and say so; never fabricate their content.

The bar is single-sourced with the author. The author's techniques — the C4 view choice, arc42 section framing, ATAM tradeoff analysis, 4+1 views, the Mermaid diagram form — are aids the reviewer judges by OUTCOME (is the boundary drawn? are decisions linked + traced? is each NFR target realized?), never conditions to demand. But note the boundary: the ADR mechanism (cond-4), NFR-realization (cond-6), and the system-level observability stance (cond-7) ARE real, load-bearing conditions for an architecture doc — they are not "invented" conditions. What stays an aid is the technique (C4/arc42/ATAM/4+1/diagram-choice), not the outcome (a linked ADR, a realized target, a named operability signal).

When to activate

• A finished architecture doc needs an accept/revise decision before engineers build within it (or before a feature's technical-design is placed within it).
• You are the independent reviewer / gate for an architecture doc a producer just authored.
• Re-judging a revised architecture doc after a prior revise verdict.
• Reviewing an amend — an approved architecture doc + a change request — as a delta-scoped review (cond-10).

Do NOT activate when:

• Authoring or repairing an architecture doc → use authoring-architecture-doc. This skill never writes the doc.
• Reviewing the upstream PRD / product direction (what/why, the NFR targets) → use a PRD-review skill. This gate judges how the whole system is structured, one layer down.
• Reviewing one feature's technical-design (a TDD — how one feature is built within the architecture) → use reviewing-technical-design, one altitude lower.
• Reviewing the api-spec or data-model themselves (the wire contract / persisted schema) → those are their own documents this architecture doc references, with their own gates.
• Reviewing a generic / ad-hoc engineering design doc, RFC, standalone ADR, spec, or plan (one not produced as the doc-library architecture-doc artifact) → use design-review, which verifies design claims against the codebase across those types. This gate is for the doc-library architecture-doc artifact — identified authoritatively by the template: architecture-doc frontmatter; a # Architecture: heading is a fallback signal only when frontmatter is absent (a generic doc that merely titles itself "Architecture" without the stamp stays with design-review; a standalone ADR not part of an architecture-doc artifact also stays with design-review).
• Checking template/section conformance → that is a template concern. This skill judges quality against the bar, not whether every heading is present.

Workflow

Step 1: Read the whole architecture with fresh, independent eyes — with the ADR files at hand

Read the architecture doc end to end as if encountering the system for the first time, without the author's framing. Your stance is a gatekeeper for everyone who builds within the system: a finding carries weight only when it shows a reader cannot grasp the structure or place a feature within it without re-deriving something the doc should have settled. Keep the linked ADR files open (cond-4 needs them) plus the upstream PRD / product direction (cond-8 traces against it) and the api-spec / data-model the doc references (cond-2 altitude check). Is this an amend? If you were handed a change request / delta against an existing doc, run the delta-scoped path (cond-10 active; scope the review to the changed decisions/structure + their ripple). On a greenfield first build no change request is present — cond-10 is n/a.

Step 2: Run the architecture-quality checklist — judge each condition

For each condition below, decide pass or gap. A condition fails only on a real, named deficiency — "I'd have structured it differently" is not a gap. For each gap, capture the exact location and what is missing (Step 4 turns it into an actionable finding). The conditions are the single-sourced bar; do not add private ones.

The capability-boundary checklist item (below) applies ONLY when a capability_record was injected into the authoring invocation and is available as review context. When absent, treat it as n/a — do not penalise a document for lacking capability-boundary markers when no boundary was defined.

1. Context, boundary + concerns covered. A new reader can state what the system is and is not responsible for: the boundary (in / explicitly-out + owner) is explicit, every actor + external dependency is named, a context diagram agrees with the prose, and every identified stakeholder concern is framed by some section/view. Gap on an implied boundary, an unnamed external dependency, or a named concern no section addresses. (Non-collapsing baseline: the boundary + the external set are always stated — their absence hides integration risk.)
2. Structure + altitude. Every major component is named once with a single responsibility + kind (no unexplained boxes); the topology states direction + protocol/style per edge; integration boundaries name a contract owner; the doc stays at whole-system altitude — major interfaces + data stores named structurally, NOT every endpoint (api-spec), every table (data-model), or one feature's implementation (TDD). Gap on a god-component, an unexplained box, an edge with no direction/protocol, or altitude slip into endpoint/table/feature detail. (Non-collapsing baseline: one-responsibility-per-component + altitude.)
3. Diagrams ⇄ narrative in sync. Every box/arrow in a diagram appears in the prose and vice-versa; diagrams read standalone; a runtime/deployment view is present where load-bearing. Gap on a diagram element the prose never explains (or a prose component the diagram omits), or a multi-service/multi-env system with no deployment view. (Collapse: a trivial system needs few/no diagrams; the sync rule holds wherever a diagram exists.)
4. The ADR mechanism (the signature condition). Every significant decision is a standalone, LINKED ADR file (one decision per file) — not inline-embedded in the doc; the decisions index ⇄ ADR files are in sync (live links both ways, superseded entries marked); and no accepted ADR is rewritten (a change is a new superseding ADR). Gap on a decision pasted inline instead of a linked ADR, an ADR bundling two decisions, a dangling/missing index link, or an accepted ADR edited in place (history destroyed). (Non-collapsing baseline: a rewritten accepted ADR is broken at any size; a thin system simply has fewer ADRs. Unverifiable if the ADR files were not handed in — flag, do not fabricate.)
5. Significant decisions traced + justified. Each significant choice/decision (runtime, datastore, messaging, hosting, trust model — the costly-to-change ones) names its driver (a requirement / NFR / ASR) and a real (non-strawman) alternative with the trade-off it lost on. Gap on a load-bearing choice with no driver, or no considered alternative ("we chose X" by assertion). "Team default" is acceptable if stated. (Non-collapsing baseline — the trade-off discipline holds at any size.)
6. NFR realization + tradeoffs. Every NFR target the PRD names has a realizing mechanism (not a restated target); for a load-bearing target it is measurable (a quality-attribute scenario with a response-measure); quality-attribute tradeoffs are named + resolved where two attributes conflict. Gap on a restated target with no mechanism, a "highly available" claim with an undiscussed single point of failure, or a clear tension (latency vs consistency, cost vs availability) never named. (Collapse: a thin system with no hard NFR keeps this light; a mechanism serving no target is over-engineering.)
7. Cross-cutting concerns addressed where the system has the surface. A resilience stance per integration boundary (timeout/retry/circuit-breaker/fallback/degrade); security (trust boundaries / authn-authz / secrets / untrusted input); privacy where sensitive data flows; and a system-level observability strategy (the golden-signal / health / SLO-monitoring posture that makes the system operable). Gap on an external dependency with no slow/down stance, an external-facing system with no trust boundary, or a multi-service system with no observability strategy. (Collapse: a single-process tool with no external deps legitimately collapses most of this; any external dependency that EXISTS gets a failure stance, any external surface a security stance.)
8. Requirements / ASR coverage. Every architecturally-significant requirement has a realizing structure/decision (no uncovered ASR); no major structure exists with no driver (no orphan). Usable downstream: a feature's technical-design can place itself within the architecture without asking the author. Gap on an ASR with no realizing structure, or a component/subsystem serving no requirement. (Collapse: a one-requirement system traces trivially.)
9. Assumptions explicit + grounded, not fabricated; consistent with the real system. Genuine unknowns are surfaced as assumptions / open questions, not papered as settled fact; nothing (a topology, a benchmark, a vendor claim, a rationale) is invented to look complete; and claims about what the system IS are verified against the real code/topology (cite file:line; mark unverified where unconfirmable) — the consistency-with-the-shipped-system check design-review formerly provided. Gap on a falsely-complete read, a fabricated limit/mechanism, or a claim about existing behaviour that contradicts the code. (Greenfield clause — non-collapsing baseline of no-fabrication, BUT: when there is no existing code/system to verify against (a brand-new system, or a fictional/example doc), the consistency check is N/A and never a blocker — mark it unverified, do not false-revise.)
10. (Amend only) delta is well-scoped, ripple-clean, versioned. When reviewing a change against an existing architecture doc: the delta meets conditions 1–9 on the elements it touched; decisions changed via a new superseding ADR (no accepted ADR rewritten) with the index in sync; the changed structure still traces to a driver (or an upstream-PRD-amend-needed is flagged); the downward-broad ripple is handled (the dependent per-feature technical-design fleet + the api-spec/data-model/deployment/runbook the change touches are named); the doc's own version is bumped + a changelog (who/when/what/why) present. Gap on an un-scoped delta, a rewritten accepted ADR, an out-of-sync index, an un-flagged ripple, or missing change history. (Collapse: on a greenfield first build this condition is n/a — do NOT full-re-review an unchanged doc, and do NOT demand a changelog on a first draft.)

1. Capability coverage (n/a when no capability records): all active capabilities appear as named components; depends_on DAG reflected in dependency diagram.

Proportionality. "Graspable + placeable without re-deriving" scales with the system. A thin product legitimately collapses what it does not need — one component → no topology; single-process → no deployment view; no external dep → no resilience matrix; no hard NFR → light §6; no sensitive data → no privacy; first draft → no changelog. Judge completeness-of-decisions + the surface-area floor, not word count or template-section presence. A small, complete architecture that satisfies every applicable condition passes. Do not manufacture a gap from brevity.

Step 3: Decide the verdict

• approve — every applicable condition passes. A new engineer can grasp the system and place a feature's design within it without re-deriving the architecture; the major decisions are justified + recorded. Approve even if you can imagine stylistic improvements; the bar is graspability + buildability, not perfection.
• revise — one or more conditions have a real, named gap (an unnamed external dependency, an unexplained box, a decision embedded inline instead of a linked ADR, a rewritten accepted ADR, an NFR target restated with no mechanism, an external dependency with no failure stance, an orphan structure, a fabricated claim, an un-scoped/ripple-broken amend, etc.).

Do not revise to signal effort or to request nice-to-haves. A condition is either met or it isn't.

Step 4: Emit the verdict + actionable findings

Emit the verdict as a single line — the literal text VERDICT: approve or VERDICT: revise, on its own line, with no surrounding code fences, quotes, or extra words (the fences here are illustration only):

VERDICT: approve

Then, on the following lines, list findings. On revise, every finding is actionable — the failed condition, the exact location, and how to fix it — so the author can resolve it in one pass. On approve, findings are optional non-blocking notes; do not let them imply a revision is required.

A good finding names the gap and the fix:

> revise — ADR mechanism (cond. 4), §7 + body: the "we chose PostgreSQL over DynamoDB" decision is written inline in §5 with its full context/alternatives/consequences, not recorded as a linked ADR. Fix: move it to a standalone adr/0003-datastore.md (Nygard shape), and link it from the §7 decisions index — so the decision is independently addressable and the index is the single source.

A bad finding is vague and unactionable:

> The decisions section could be tightened up. (Which decision? Why does it fail the bar? What fixes it?)

Rules

Hard rules (never violate):

• Emit exactly one verdict line, VERDICT: approve or VERDICT: revise — that literal token, on its own line, nothing else on it. Downstream tooling parses it.
• Judge, never author. Return findings; do not rewrite, fix, or fill in the doc. The producer revises.
• Single-sourced bar. Judge against the ten conditions in Step 2 — the same bar the author (authoring-architecture-doc Step-7) produces to. Do not invent extra conditions or apply a stricter private standard.
• Aids are judged by outcome, never demanded. C4/arc42/ATAM/4+1 framing, the diagram-type choice, are the author's techniques — judge whether the boundary is drawn / decisions linked + traced / each target realized, NEVER "you didn't use C4 / draw a

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bm629
• Source: bm629/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.