review-architecture

name

review-architecture

description

Review a written architecture artifact — an ADR (docs/adr/), a broader architecture doc, or the architecture section of a design doc — 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) plus decision soundness and reversibility. Use after an ADR or architecture doc 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).

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:

• Claim Set (the Pass 0 output) presented verbatim as the inspectable intermediate artifact
• Per-claim verdicts by dimension, a Not Reviewed section, and Pass 2 findings — all per output-contract.md
• Next steps confirmation from user

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 (ADR 0004), 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:

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

2. 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);
   • 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.

3. 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. See output-contract.md for full invocation/scope rules.