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).