/architecture-review

name: architecture-review
description: Conducts a comprehensive multi-perspective architecture review using ALL architecture team members. Use when the user requests "Start architecture review", "Full architecture review", "Review architecture for version X.Y.Z", "Conduct comprehensive review", or when they want assessment from multiple perspectives. Do NOT use for single-specialist reviews (use specialist-review instead) or for status checks (use architecture-status instead).
allowed-tools: Read,Write,Glob,Grep,Bash(git:*),Agent

Architecture Review (orchestrator)

Comprehensive multi-perspective architecture review. This skill is an **orchestrator** — it dispatches one subagent invocation per active team member in parallel, then aggregates the returned reviews into a consolidated document. The deep-perspective work happens in the subagents (`agents/<id>.md`), not in this skill's main thread.

See [ADR-013](../../.architecture/decisions/adrs/ADR-013-skill-orchestrator-subagent-delegation.md) for the rationale.

Process

1. Determine scope

Identify the review target from the user's request:

• **Version** — "version 2.0.0" → filename `2-0-0.md`
• **Feature** — "authentication feature" → filename `feature-authentication.md`
• **Component** — "payments module" → filename `component-payments-module.md`

Apply input sanitization from [`../_patterns.md`](../_patterns.md). If the scope is ambiguous, ask one clarifying question and stop.

2. Load team and config

Read `.architecture/config.yml` and `.architecture/members.yml`:

• `config.yml.pragmatic_mode.enabled` decides whether to include the `pragmatic_enforcer` subagent.
• `members.yml.members[]` is the list of subagents to dispatch.

Each member's `id` (e.g., `security_specialist`) maps to `agents/<kebab-id>.md` (e.g., `agents/security-specialist.md`). The drift check in CI guarantees these files exist and are in sync.

**Active set**: every member in `members.yml`, **excluding** `pragmatic_enforcer` if `config.yml.pragmatic_mode.enabled == false`.

Also read `.architecture/principles.md`. It is the project's recorded constitution, and every review is checked against it: step 4 hands it to each member, step 6.5 collects what they found. If the file is missing, write "no principles recorded" in the review's Principle Conflicts section and skip the gate. Never block a review on it.

3. Optional pre-analysis (orchestrator-side)

For broad reviews, an initial scan helps the orchestrator give every subagent a shared starting context. Use `Glob`, `Grep`, and `Bash(git:*)` (e.g., `git log --oneline -20`, `git diff main...HEAD --stat`) to assemble a short brief: target description, recent activity, key files. Keep this brief under ~500 tokens — it's a shared header, not a review.

If the review target is narrow (a single feature or ADR), this step can be skipped.

4. Dispatch subagents in parallel

Issue **one Agent call per active member, all in the same response** (parallel dispatch is the documented best practice for independent work):

Agent({
  subagent_type: "<kebab-id>",
  description: "<Title> review of <target>",
  prompt: <see template below>
})

**Prompt template** (used for every subagent — vary only the `<target>`, the optional shared brief, and the principles block):

Conduct a focused review of: <target>.

<optional shared brief from step 3>

Recorded principles (.architecture/principles.md, the "Core Principles"
section verbatim; drop the quotations above it):
<principles>

Apply your perspective (your subagent file lists your specialty,
disciplines, skillsets, and domains). Stay within your specialty —
other team members are reviewing concurrently and will cover their
own areas.

Return a markdown review with:
- Perspective statement (1-2 sentences from your unique vantage)
- Key observations (3-5)
- Strengths within your domain (3-5)
- Concerns, each with severity (critical / high / medium / low),
  confidence (0.0-1.0), location (file:line where applicable),
  why-it-matters, concrete fix. Confidence is your own estimate that
  the concern is real: 0.9+ means you opened the code and confirmed
  it; 0.5 or below means you are inferring from names, patterns, or
  files you did not read. Never omit it and never round it up.
- Recommendations, ordered: immediate / short-term / long-term, with
  rough effort estimates (S/M/L)
- Risks if unaddressed
- Principle conflicts: every concern above that violates a recorded
  principle, restated as "<principle name>: <one line>". Every
  recommendation that would change or retire a recorded principle,
  labeled PRINCIPLE CHANGE with the principle named. Write "none"
  when there are none. Do not omit the section.

Read code, configs, and ADRs as needed via your scoped tools. Cite
exact file paths and line numbers. Do not range outside your
specialty.

For `pragmatic_enforcer` (when included), append: `Apply the Pragmatic Enforcer Analysis structure from .architecture/templates/adr-template.md (Necessity, Complexity, Ratio, Recommendation).`

5. Challenge round

The individual reviews are monologues: no member has seen another's findings. Before aggregating, run one adversarial pass over the findings that carry the most weight. This is the `collaborative_phase` from `members.yml`, made concrete.

1. **Select** every concern rated **critical** or **high** across all returned reviews. Medium and low findings skip this round. 2. **Assign a challenger** per finding: the active member best positioned to refute it, never its author. Use the members' `perspective` and `domains` fields — a security critical demanding mandatory validation goes to `performance_specialist`; an architectural rewrite goes to `pragmatic_enforcer` (when active) or `maintainability_expert`; a domain-model concern goes to `systems_architect`. When no member is an obvious counterweight, use `pragmatic_enforcer` if active, otherwise skip the finding and note it as unchallenged. 3