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: 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. No match → assign a new ID: next available TR-[system]-NNN for that system, starting from the highest existing sequence + 1. 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: Read every ADR's "GDD Requirements Addressed" section Check if it explicitly references the requirement or its GDD Check if the ADR's decision text implicitly covers the requirement Mark coverage status: Status Meaning ✅ Covered An ADR explicitly addresses this requirement ⚠️ Partial An ADR partially covers this, or coverage is ambiguous ❌ Gap No ADR addresses this requirement Build the full matrix: ## Traceability Matrix | Requirement ID | GDD | System | Requirement | ADR Coverage | Status | |---------------|-----|--------|-------------|--------------|--------| | TR-combat-001 | combat.md | Combat | Hitbox detection < 1 frame | ADR-0003 | ✅ | | TR-combat-002 | combat.md | Combat | Combo window timing | — | ❌ GAP | | TR-inventory-001 | inventory.md | Inventory | Persistent item storage | ADR-0005 | ✅ | Count the totals: X covered, Y partial, Z gaps. Phase 3b: Story and Test Linkage (RTM mode only) Skip this phase unless the argument is rtm or full with stories present. This phase extends the Phase 3 matrix to include the story that implements each requirement and the test that verifies it — producing the full Requirements Traceability Matrix (RTM). Step 3b-1 — Load stories Glob production/epics/**/*.md (excluding EPIC.md index files). For each story file: Extract TR-ID from the story's Context section Extract story file path, title, Status Extract ## Test Evidence section — the stated test file path Step 3b-2 — Load test files Glob tests/unit/**/*_test.* and tests/integration/**/*_test.* . Build an index: system → [test file paths]. For each test file path from Step 3b-1, confirm via Glob whether the file actually exists. Note MISSING if the stated path does not exist. Step 3b-3 — Build the extended RTM For each TR-ID in the Phase 3 matrix, add: Story : the story file path(s) that reference this TR-ID (may be multiple) Test File : the test file path stated in the story's Test Evidence section Test Status : COVERED (test file exists) / MISSING (path stated but not found) / NONE (no test path stated, story type may be Visual/Feel/UI) / NO STORY (requirement has no story yet — pre-production gap) Extended matrix format: ## Requirements Traceability Matrix (RTM) | TR-ID | GDD | Requirement | ADR | Story | Test File | Test Status | |-------|-----|-------------|-----|-------|-----------|-------------| | TR-combat-001 | combat.md | Hitbox < 1 frame | ADR-0003 | story-001-hitbox.md | tests/unit/combat/hitbox_test.gd | COVERED | | TR-combat-002 | combat.md | Combo window | — | story-002-combo.md | — | NONE (Visual/Feel) | | TR-inventory-001 | inventory.md | Persistent storage | ADR-0005 | — | — | NO STORY | RTM coverage summary: COVERED: [N] — requirements with ADR + story + passing test MISSING test: [N] — story exists but test file not found NO STORY: [N] — requirements with ADR but no story yet NO ADR: [N] — requirements without architectural coverage (from Phase 3 gaps) Full chain complete (COVERED): [N/total] ([%]) Phase 4: Cross-ADR Conflict Detection Compare every ADR against every other ADR to detect contradictions. A conflict exists when: Data ownership conflict : Two ADRs claim exclusive ownership of the same data Integration contract conflict : ADR-A assumes System X has interface Y, but ADR-B defines System X with a different interface Performance budget conflict : ADR-A allocates N ms to physics, ADR-B allocates N ms to AI, together they exceed the total frame budget Dependency cycle : ADR-A says System X initialises before Y; ADR-B says Y initialises before X Architecture pattern conflict : ADR-A uses event-driven communication for a subsystem; ADR-B uses direct function calls to the same subsystem State management conflict : Two ADRs define authority over the same game state (e.g. both Combat ADR and Character ADR claim to own the health value) For each conflict found: ## Conflict: [ADR-NNNN] vs [ADR-MMMM] Type: [Data ownership / Integration / Performance / Dependency / Pattern / State] ADR-NNNN claims: [...] ADR-MMMM claims: [...] Impact: [What breaks if both are implemented as written] Resolution options: 1. [Option A] 2. [Option B] ADR Dependency Ordering After conflict detection, analyse the dependency graph across all ADRs: Collect all Depends On fields from every ADR's "ADR Dependencies" section Topological sort : Determine the correct implementation order — ADRs with no dependencies come first (Foundation), ADRs that depend on those come next, etc. Flag unresolved dependencies : If ADR-A's "Depends On" field references an ADR that is still Proposed or does not exist, flag it: ⚠️ ADR-0005 depends on ADR-0002 — but ADR-0002 is still Proposed. ADR-0005 cannot be safely implemented until ADR-0002 is Accepted. Cycle detection : If ADR-A depends on ADR-B and ADR-B depends on ADR-A (directly or transitively), flag it as a DEPENDENCY CYCLE : 🔴 DEPENDENCY CYCLE: ADR-0003 → ADR-0006 → ADR-0003 This cycle must be broken before either can be implemented. Output recommended implementation order : ### Recommended ADR Implementation Order (topologically sorted) Foundation (no dependencies): 1. ADR-0001: [title] 2. ADR-0003: [title] Depends on Foundation: 3. ADR-0002: [title] (requires ADR-0001) 4. ADR-0005: [title] (requires ADR-0003) Feature layer: 5. ADR-0004: [title] (requires ADR-0002, ADR-0005) Phase 5: Engine Compatibility Cross-Check Across all ADRs, check for engine consistency: Version Consistency Do all ADRs that mention an engine version agree on the same version? If any ADR was written for an older engine version, flag it as potentially stale Post-Cutoff API Consistency Collect all "Post-Cutoff APIs Used" fields from all ADRs For each, verify against the relevant module reference doc Check that no two ADRs make contradictory assumptions about the same post-cutoff API Deprecated API Check Grep all ADRs for API names listed in deprecated-apis.md Flag any ADR referencing a deprecated API Missing Engine Compatibility Sections List all ADRs that are missing the Engine Compatibility section entirely These are blind spots — their engine assumptions are unknown Output format: ### Engine Audit Results Engine: [name + version] ADRs with Engine Compatibility section: X / Y total Deprecated API References: - ADR-0002: uses [deprecated API] — deprecated since [version] Stale Version References: - ADR-0001: written for [older version] — current project version is [version] Post-Cutoff API Conflicts: - ADR-0004 and ADR-0007 both use [API] with incompatible assumptions Engine Specialist Consultation After completing the engine audit above, spawn the primary engine specialist via Task for a domain-expert second opinion: Read .claude/docs/technical-preferences.md Engine Specialists section to get the primary specialist If no engine is configured, skip this consultation Spawn subagent_type: [primary specialist] with: all ADRs that contain engine-specific decisions or Post-Cutoff APIs Used fields, the engine reference docs, and the Phase 5 audit findings. Ask them to: Confirm or challenge each audit finding — specialists may know of engine nuances not captured in the reference docs Identify engine-specific anti-patterns in the ADRs that the audit may have missed (e.g., using the wrong Godot node type, Unity component coupling, Unreal subsystem misuse) Flag ADRs that make assumptions about engine behaviour that differ from the actual pinned version Incorporate additional findings under ### Engine Specialist Findings in the Phase 5 output. These feed into the final verdict — specialist-identified issues carry the same weight as audit-identified issues. Phase 5b: Design Revision Flags (Architecture → GDD Feedback) For each HIGH RISK engine finding from Phase 5, check whether any GDD makes an assumption that the verified engine reality contradicts. Specific cases to check: Post-cutoff API behaviour differs from training-data assumptions : If an ADR records a verified API behaviour that differs from the default LLM assumption, check all GDDs that reference the related system. Look for design rules written around the old (assumed) behaviour. Known engine limitations in ADRs : If an ADR records a known engine limitation (e.g. "Jolt ignores HingeJoint3D damp", "D3D12 is now the default backend"), check GDDs that design mechanics around the affected feature. Deprecated API conflicts : If Phase 5 flagged a deprecated API used in an ADR, check whether any GDD contains mechanics that assume the deprecated API's behaviour. For each conflict found, record it in the GDD Revision Flags table: ### GDD Revision Flags (Architecture → Design Feedback) These GDD assumptions conflict with verified engine behaviour or accepted ADRs. The GDD should be revised before its system enters implementation. | GDD | Assumption | Reality (from ADR/engine-reference) | Action | |-----|-----------|--------------------------------------|--------| | combat.md | "Use HingeJoint3D damp for weapon recoil" | Jolt ignores damp — ADR-0003 | Revise GDD | If no revision flags are found, write: "No GDD revision flags — all GDD assumptions are consistent with verified engine behaviour." Before asking, display the proposed change inline — show the current systems-index row for each flagged GDD and the proposed updated row side by side so the user can see exactly what will change. Then use AskUserQuestion : "I found [N] GDD revision flag(s). May I update the systems index?" [A] Yes — apply all [N] updates to the systems index now [B] Show me the full diff first, then ask again [C] No — leave the systems index unchanged for now If [A]: apply the updates. Status field must be exactly Needs Revision — no parentheticals (other skills match that exact string and parentheticals break the match). If [B]: display the complete proposed systems-index section, then re-ask with AskUserQuestion .