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:

For each GDD, produce a structured list:

``` GDD: [filename] System: [system name] Technical Requirements: T