/architecture-review

name: architecture-review
description: "Validates completeness and consistency of the project architecture against all GDDs. Builds a traceability matrix mapping every GDD technical requirement to ADRs, identifies coverage gaps, detects cross-ADR conflicts, verifies engine compatibility consistency across all decisions, and produces a PASS/CONCERNS/FAIL verdict. The architecture equivalent of /design-review."
argument-hint: "[focus: full | coverage | consistency | engine | single-gdd path/to/gdd.md]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Task, AskUserQuestion
agent: technical-director
model: opus

Architecture Review

The architecture review validates that the complete body of architectural decisions covers all game design requirements, is internally consistent, and correctly targets the project's pinned engine version. It is the quality gate between Technical Setup and Pre-Production.

**Argument modes:**

• **No argument / `full`**: Full review — all phases
• **`coverage`**: Traceability only — which GDD requirements have no ADR
• **`consistency`**: Cross-ADR conflict detection only
• **`engine`**: Engine compatibility audit only
• **`single-gdd [path]`**: Review architecture coverage for one specific GDD
• **`rtm`**: Requirements Traceability Matrix — extends the standard matrix

to include story file paths and test file paths; outputs `docs/architecture/requirements-traceability.md` with the full GDD requirement → ADR → Story → Test chain. Use in Production phase when stories and tests exist.

---

Phase 1: Load Everything

Phase 1a — L0: Summary Scan (fast, low tokens)

Before reading any full document, use Grep to extract `## Summary` sections from all GDDs and ADRs:

Grep pattern="## Summary" glob="design/gdd/*.md" output_mode="content" -A 4
Grep pattern="## Summary" glob="docs/architecture/adr-*.md" output_mode="content" -A 3

For `single-gdd [path]` mode: use the target GDD's summary to identify which ADRs reference the same system (Grep ADRs for the system name), then full-read only those ADRs. Skip full-reading unrelated GDDs entirely.

For `engine` mode: only full-read ADRs — GDDs are not needed for engine checks.

For `coverage` or `full` mode: proceed to full-read everything below.

Phase 1b — L1/L2: Full Document Load

Read all inputs appropriate to the mode:

Design Documents

• All in-scope GDDs in `design/gdd/` — read every file completely
• `design/gdd/systems-index.md` — the authoritative list of systems

Architecture Documents

• All in-scope ADRs in `docs/architecture/` — read every file completely
• `docs/architecture/architecture.md` if it exists

Engine Reference

• `docs/engine-reference/[engine]/VERSION.md`
• `docs/engine-reference/[engine]/breaking-changes.md`
• `docs/engine-reference/[engine]/deprecated-apis.md`
• All files in `docs/engine-reference/[engine]/modules/`

Project Standards

• `.claude/docs/technical-preferences.md`

Report a count: "Loaded [N] GDDs, [M] ADRs, engine: [name + version]."

**Also read `docs/consistency-failures.md`** if it exists. Extract entries with Domain matching the systems under review (Architecture, Engine, or any GDD domain being covered). Surface recurring patterns as a "Known conflict-prone areas" note at the top of the Phase 4 conflict detection output.

---

Phase 2: Extract Technical Requirements from Every GDD

Pre-load the TR Registry

Before extracting any requirements, read `docs/architecture/tr-registry.yaml` if it exists. Index existing entries by `id` and by normalized `requirement` text (lowercase, trimmed). This prevents ID renumbering across review runs.

For each requirement you extract, the matching rule is: 1. **Exact/near match** to an existing registry entry for the same system → reuse that entry's TR-ID unchanged. Update the `requirement` text in the registry only if the GDD wording changed (same intent, clearer phrasing) — add a `revised: [date]` field. 2. **No match** → assign a new ID: next available `TR-[system]-NNN` for that system, starting from the highest existing sequence + 1. 3. **Ambiguous** (partial match, intent unclear) → ask the user: > "Does '[new requirement text]' refer to the same requirement as > `TR-[system]-NNN: [existing text]'`, or is it a new requirement?" User answers: "Same requirement" (reuse ID) or "New requirement" (new ID).

For any requirement with `status: deprecated` in the registry — skip it. It was removed from the GDD intentionally.

For each GDD, read it and extract all **technical requirements** — things the architecture must provide for the system to work. A technical requirement is any statement that implies a specific architectural decision.

Categories to extract:

| Category | Example | |----------|---------| | **Data structures** | "Each entity has health, max health, status effects" → needs a component/data schema | | **Performance constraints** | "Collision detection must run at 60fps with 200 entities" → physics budget ADR | | **Engine capability** | "Inverse kinematics for character animation" → IK system ADR | | **Cross-system communication** | "Damage system notifies UI and audio simultaneously" → event/signal architecture ADR | | **State persistence** | "Player progress persists between sessions" → save system ADR | | **Threading/timing** | "AI decisions happen off the main thread" → concurrency ADR | | **Platform requirements** | "Supports keyboard, gamepad, touch" → input system ADR |

For each GDD, produce a structured list:

GDD: [filename]
System: [system name]
Technical Requirements:
  TR-[GDD]-001: [requirement text] → Domain: [Physics/Rendering/etc]
  TR-[GDD]-002: [requirement text] → Domain: [...]

This becomes the **requirements baseline** — the complete set of what the architecture must cover.

---

Phase 3: Build the Traceability Matrix

For each technical requirement extracted in Phase 2, search the ADRs:

1. Read every ADR's "GDD