Architecture Review
Overview
Review a single committed architecture artifact against the system it describes. The review is claim-driven: the artifact is normalized into an explicit, inspectable claim-set (Pass 0), each claim is verified for the existence and topology of the mechanism it names (Pass 1), and the artifact's decisions are graded against its own stated context (Pass 2). Verification is delegated to the read-only architecture-reviewer agent; this skill owns acceptance and presentation.
The altitude line — the load-bearing constraint. This skill verifies that declared mechanisms exist and are wired into the right topology — "is there an idempotency-key column / a circuit breaker targeting dependency D / a /v2/ route." It never verifies behavioral correctness ("does the code use the key correctly under retries") — that belongs to $kk:review-code and $kk:review-spec. Every dimension, the input contract, and the eval strategy are consequences of this line. Do not let a dimension expand into whole-system behavioral reasoning.
Security architecture is delegated OUT to the PAL secaudit tool (mcp__pal__secaudit). There is no kk: security skill. Trust boundaries, authN/authZ enforcement, and data-classification flow drag the reviewer into runtime analysis — surface such claims under Not Reviewed with a secaudit pointer (see output-contract.md).
Conventions
Profiles are not consulted in M1 — evidence-gathering mechanics ship as inline examples in the pass procedures. Profile detection and an architecture/ profile phase are deferred (see the review design §8).
Required Outputs
Before declaring the review complete, verify all outputs are delivered:
Workflow
Mandatory ordering — instructions before artifact
The workflow below is strictly sequential. Do not read the artifact's content, extract claims, or form any verdict until you have loaded every instruction file: this SKILL.md, input-contract.md, and output-contract.md. Your only early contact with the input is the artifact path(s) passed on invocation — enough to apply the acceptance contract, not enough to pattern-match claims. The pass procedures (pass0-extraction.md, pass1-topology.md, pass2-soundness.md) are the delegated agent's to load; the agent restates the same instruction-before-action rule on its own side.
This ordering is load-bearing, not stylistic: with the artifact text in context before the contracts are loaded, the model has enough to emit plausible claims and verdicts and will optimize away the methodology.
Phases:
Acceptance — apply input-contract.md to the invocation path(s): exactly one committed written artifact per invocation; diagrams count only with accompanying prose; verbal/diagram-only or multi-artifact inputs are rejected with an actionable message. A domain-reference kit is the one composite exception: pass either kit page's path and resolve the counterpart (<context>.md ↔ <context>-traps.md sibling naming, cross-link fallback) so the pair is reviewed as one artifact — two explicit paths are still rejected, and an unresolvable counterpart means the page is reviewed solo with a loud report note. No path given → list candidate artifacts (docs/adr/, docs/wip/*/design.md) and ask. This is the only phase the main agent performs against the input directly, and it reads the artifact's shape, not its claims.
Delegate to architecture-reviewer — spawn the read-only architecture-reviewer agent (via the Agent tool) to run Pass 0 → Pass 1 → Pass 2. The agent has no shell, so resolve the plugin root yourself first (echo "${TOOLBOX_PLUGIN_ROOT:-NOT_SET}") and inject the absolute path under a ## Plugin Root heading. Pass the agent:
- the accepted artifact path (and, for a design doc, the scoping heading; for a composite domain-reference kit, both resolved page paths — or the solo page plus the unresolvable-counterpart note);
- the procedure files to read, by plugin-root path:
../../skills/review-architecture/pass0-extraction.md, ../../skills/review-architecture/pass1-topology.md, ../../skills/review-architecture/pass2-soundness.md, and ../../skills/review-architecture/output-contract.md;
- the resolved
## Plugin Root absolute path.
Present — relay the agent's report verbatim per output-contract.md — do not summarize, compress, or re-narrate it: the full Claim Set table, per-dimension verdicts, the Not Reviewed section (delegated/unrouted claims), and Pass 2 findings, with the verdict→severity mapping applied. A summarized relay destroys the inspectable intermediate artifact the Claim Set exists to be (the read-only agent has no other home for it). Then confirm next steps with the user.
Invocation
$kk:review-architecture <artifact-path>
Exactly one artifact per invocation. For a design doc, an optional heading argument scopes the review to its architecture section. For a domain-reference kit, pass either page's path — the glossary/traps counterpart is auto-discovered and the pair is reviewed as one composite artifact. See output-contract.md for full invocation/scope rules.
1---2name: review-architecture3description: Review a written architecture artifact — an ADR (docs/adr/), a broader architecture doc, the architecture section of a design doc, or a domain-reference kit (glossary + traps pages, reviewed as one composite artifact) — against the system it claims to describe. Verifies the EXISTENCE and TOPOLOGY of declared mechanisms (structural boundaries, data ownership, NFR mechanisms, failure isolation, state consistency, evolution/versioning, domain binding) plus decision soundness, reversibility, and provenance (self-certification of reverse-engineered claims). Use after an ADR, architecture doc, domain glossary, or domain kit is written, before or during implementation. NOT for behavioral/runtime correctness (that is $kk:review-code and $kk:review-spec). Security architecture is out of scope — delegate threat modeling to the PAL secaudit tool (mcp__pal__secaudit).4---5<!-- codex: tool-name mapping applied. See .codex/scripts/session-start.sh -->67# Architecture Review89## Overview1011Review a single committed architecture artifact against the system it describes. The review is **claim-driven**: the artifact is normalized into an explicit, inspectable claim-set (Pass 0), each claim is verified for the existence and topology of the mechanism it names (Pass 1), and the artifact's decisions are graded against its own stated context (Pass 2). Verification is delegated to the read-only `architecture-reviewer` agent; this skill owns acceptance and presentation.1213**The altitude line — the load-bearing constraint.** This skill verifies that declared mechanisms *exist* and are wired into the right *topology* — "is there an idempotency-key column / a circuit breaker targeting dependency D / a `/v2/` route." It never verifies behavioral correctness ("does the code *use* the key correctly under retries") — that belongs to `$kk:review-code` and `$kk:review-spec`. Every dimension, the input contract, and the eval strategy are consequences of this line. Do not let a dimension expand into whole-system behavioral reasoning.1415**Security architecture is delegated OUT** to the PAL `secaudit` tool (`mcp__pal__secaudit`). There is no `kk:` security skill. Trust boundaries, authN/authZ enforcement, and data-classification flow drag the reviewer into runtime analysis — surface such claims under Not Reviewed with a `secaudit` pointer (see [output-contract.md](output-contract.md)).1617## Conventions1819Profiles are **not** consulted in M1 — evidence-gathering mechanics ship as inline examples in the pass procedures. Profile detection and an `architecture/` profile phase are deferred (see the review design §8).2021## Required Outputs2223Before declaring the review complete, verify all outputs are delivered:2425- [ ] Claim Set (the Pass 0 output) presented verbatim as the inspectable intermediate artifact26- [ ] Per-claim verdicts by dimension, a Not Reviewed section, and Pass 2 findings — all per [output-contract.md](output-contract.md)27- [ ] Next steps confirmation from user2829## Workflow3031### Mandatory ordering — instructions before artifact3233The workflow below is strictly sequential. **Do not read the artifact's content, extract claims, or form any verdict until you have loaded every instruction file: this SKILL.md, [input-contract.md](input-contract.md), and [output-contract.md](output-contract.md).** Your only early contact with the input is the artifact *path(s)* passed on invocation — enough to apply the acceptance contract, not enough to pattern-match claims. The pass procedures (`pass0-extraction.md`, `pass1-topology.md`, `pass2-soundness.md`) are the delegated agent's to load; the agent restates the same instruction-before-action rule on its own side.3435This ordering is load-bearing, not stylistic: with the artifact text in context before the contracts are loaded, the model has enough to emit plausible claims and verdicts and will optimize away the methodology.3637**Phases:**38391. **Acceptance** — apply [input-contract.md](input-contract.md) to the invocation path(s): exactly one committed written artifact per invocation; diagrams count only with accompanying prose; verbal/diagram-only or multi-artifact inputs are rejected with an actionable message. A domain-reference kit is the one composite exception: pass either kit page's path and resolve the counterpart (`<context>.md` ↔ `<context>-traps.md` sibling naming, cross-link fallback) so the pair is reviewed as one artifact — two explicit paths are still rejected, and an unresolvable counterpart means the page is reviewed solo with a loud report note. No path given → list candidate artifacts (`docs/adr/`, `docs/wip/*/design.md`) and ask. This is the only phase the main agent performs against the input directly, and it reads the artifact's *shape*, not its claims.40412. **Delegate to `architecture-reviewer`** — spawn the read-only `architecture-reviewer` agent (via the Agent tool) to run Pass 0 → Pass 1 → Pass 2. The agent has no shell, so resolve the plugin root yourself first (`echo "${TOOLBOX_PLUGIN_ROOT:-NOT_SET}"`) and inject the absolute path under a `## Plugin Root` heading. Pass the agent:42 - the accepted artifact path (and, for a design doc, the scoping heading; for a composite domain-reference kit, both resolved page paths — or the solo page plus the unresolvable-counterpart note);43 - the procedure files to read, by plugin-root path: `../../skills/review-architecture/pass0-extraction.md`, `../../skills/review-architecture/pass1-topology.md`, `../../skills/review-architecture/pass2-soundness.md`, and `../../skills/review-architecture/output-contract.md`;44 - the resolved `## Plugin Root` absolute path.45463. **Present** — relay the agent's report **verbatim** per [output-contract.md](output-contract.md) — do not summarize, compress, or re-narrate it: the full Claim Set table, per-dimension verdicts, the Not Reviewed section (`delegated`/`unrouted` claims), and Pass 2 findings, with the verdict→severity mapping applied. A summarized relay destroys the inspectable intermediate artifact the Claim Set exists to be (the read-only agent has no other home for it). Then confirm next steps with the user.4748## Invocation4950```51$kk:review-architecture <artifact-path>52```5354Exactly one artifact per invocation. For a design doc, an optional heading argument scopes the review to its architecture section. For a domain-reference kit, pass either page's path — the glossary/traps counterpart is auto-discovered and the pair is reviewed as one composite artifact. See [output-contract.md](output-contract.md) for full invocation/scope rules.
serpro69