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

• All in-scope GDDs in

  design/gdd/

  — read every file completely

• design/gdd/systems-index.md

  — the authoritative list of systems

• All in-scope ADRs in

  docs/architecture/

  — read every file completely

• docs/architecture/architecture.md

  if it exists

• 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/

• .claude/docs/technical-preferences.md

docs/consistency-failures.md

docs/architecture/tr-registry.yaml

id

requirement

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

status: deprecated

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

1. Read every ADR's "GDD Requirements Addressed" section
2. Check if it explicitly references the requirement or its GDD
3. Check if the ADR's decision text implicitly covers the requirement
4. Mark coverage status:

undefined

production/epics/**/*.md

• Extract

  TR-ID

  from the story's Context section
• Extract story file path, title, Status
• Extract

  ## Test Evidence

  section — the stated test file path

• 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)

undefined

• 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)

undefined

1. [Option A]
2. [Option B]

undefined

1. Collect all

   Depends On

   fields from every ADR's "ADR Dependencies" section
2. Topological sort: Determine the correct implementation order — ADRs with no dependencies come first (Foundation), ADRs that depend on those come next, etc.
3. 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.

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

5. 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)

• 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

• 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

• Grep all ADRs for API names listed in

  deprecated-apis.md

• Flag any ADR referencing a deprecated API

• List all ADRs that are missing the Engine Compatibility section entirely
• These are blind spots — their engine assumptions are unknown

undefined

• ADR-0002: uses [deprecated API] — deprecated since [version]

• ADR-0001: written for [older version] — current project version is [version]

• ADR-0004 and ADR-0007 both use [API] with incompatible assumptions

---

• 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:
  1. Confirm or challenge each audit finding — specialists may know of engine nuances not captured in the reference docs
  2. 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)
  3. Flag ADRs that make assumptions about engine behaviour that differ from the actual pinned version

### Engine Specialist Findings

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

undefined

docs/architecture/architecture.md

• Does every system from

  systems-index.md

  appear in the architecture layers?
• Does the data flow section cover all cross-system communication defined in GDDs?
• Do the API boundaries support all integration requirements from GDDs?
• Are there systems in the architecture doc that have no corresponding GDD (orphaned architecture)?

AskUserQuestion

• "Review complete. What would you like to write?"
  • [A] Write all three files (review report + traceability index + TR registry)
  • [B] Write review report only —

    docs/architecture/architecture-review-[date].md

  • [C] Don't write anything yet — I need to review the findings first

rtm

AskUserQuestion

• "May I write the full Requirements Traceability Matrix?"
  • [A] Yes — write to

    docs/architecture/requirements-traceability.md

  • [B] Not yet — show me the full RTM data first, then ask again

undefined

Last Updated: [date] Mode: /architecture-review rtm Coverage: [N]% full chain complete (GDD → ADR → Story → Test)

docs/architecture/tr-registry.yaml

• Append any new TR-IDs that weren't in the registry before this review
• Update

  requirement

  text and

  revised

  date for any entries whose GDD wording changed (ID stays the same)
• Mark

  status: deprecated

  for any registry entries whose GDD requirement no longer exists (confirm with user before marking deprecated)
• Never renumber or delete existing entries
• Update the

  last_updated

  and

  version

  fields at the top

• Total requirements: [N]
• Covered: [X] ([%])
• Partial: [Y]
• Gaps: [Z]

1. Immediate actions: List the top 3 ADRs to create (highest-impact gaps first, Foundation layer before Feature layer)
2. Pre-gate checklist: Check whether these exist via Glob and mark each ✅ or ❌:

   • tests/unit/

     and

     tests/integration/

     directories — if ❌: run

     /test-setup

   • .github/workflows/tests.yml

     — if ❌: run

     /test-setup

   • design/accessibility-requirements.md

     — if ❌: run

     /ux-design

   • design/ux/interaction-patterns.md

     — if ❌: run

     /ux-design

     Present ❌ items as required steps before gate-check. Do not offer

     /gate-check

     as an option if any item is ❌ — offer the missing skill to run instead.
3. Rerun trigger: "Re-run

   /architecture-review

   after each new ADR is written to verify coverage improves"

AskUserQuestion

• If ADR gaps remain or any pre-gate item is ❌:
  • "Architecture review complete. What would you like to do next?"
    • [A] Write a missing ADR — open a fresh session and run

      /architecture-decision [system]

    • [B] Run

      /test-setup

      — required before gate-check (only show if test infrastructure is ❌)
    • [C] Run

      /ux-design

      — required before gate-check (only show if UX/accessibility files are ❌)
    • [D] Stop here for this session
• If all pre-gate checklist items are ✅ and no blocking ADR gaps remain:
  • "Architecture review complete. All pre-gate items confirmed. What would you like to do next?"
    • [A] Run

      /gate-check pre-production

    • [B] Write a missing ADR — open a fresh session and run

      /architecture-decision [system]

    • [C] Stop here for this session

1. Surface immediately: Report "[AgentName]: BLOCKED — [reason]" before continuing
2. Assess dependencies: If the blocked agent's output is required by a later phase, do not proceed past that phase without user input
3. Offer options via AskUserQuestion with three choices:
   • Skip this agent and note the gap in the final report
   • Retry with narrower scope (fewer GDDs, single-system focus)
   • Stop here and resolve the blocker first
4. Always produce a partial report — output whatever was completed so work is not lost

1. Read silently — do not narrate every file read
2. Show the matrix — present the full traceability matrix before asking for anything; let the user see the state
3. Don't guess — if a requirement is ambiguous, ask: "Is [X] a technical requirement or a design preference?"
4. Draft before approval — always show the content that will be written (the report, the updated ADR section, the systems-index row) inline in the conversation before requesting approval. Never ask to write something the user has not yet seen.
5. Use

   AskUserQuestion

   for write approvals — plain text "May I?" is not sufficient. Use the structured tool with labeled options [A]/[B]/[C] so the user can choose between "write now", "show full draft first", and "not yet". Multi-file changesets must list every file and what changes, then ask once with grouped options — not a separate plain-text question per file.
6. Non-blocking — the verdict is advisory; the user decides whether to continue despite CONCERNS or even FAIL findings