[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7EX19CCYEC0TPZK301GBCXN":3,"skill-same:01M7EX19CCYEC0TPZK301GBCXN":50},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":29,"commitSha":30,"skillDirectory":31,"forksCount":32,"repositoryHtmlUrl":33,"repositoryHomepageUrl":6,"ownerHtmlUrl":34,"ownerBlogUrl":6,"ownerDescription":35,"updatedAt":36,"install":37,"resources":49},"01M7EX19CCYEC0TPZK301GBCXN","architecture-review",null,"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\u002FCONCERNS\u002FFAIL verdict. The architecture equivalent of \u002Fdesign-review.","lza6\u002FArmor-piercing-system-prompts","lza6","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F128880206?v=4","01M7EB3K7WPX5T28EJ2NVHE6EG","Chinese-tingfeng","01M7EB3K97E1KQ16QWKJMFNGX8",11,"MIT","https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F05-技能与代理开发\u002Farchitecture-review\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: architecture-review\ndescription: \"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\u002FCONCERNS\u002FFAIL verdict. The architecture equivalent of \u002Fdesign-review.\"\nargument-hint: \"[focus: full | coverage | consistency | engine | single-gdd path\u002Fto\u002Fgdd.md]\"\nuser-invocable: true\nallowed-tools: Read, Glob, Grep, Write, Task, AskUserQuestion\nagent: technical-director\nmodel: opus\n---\n\n# Architecture Review\n\nThe architecture review validates that the complete body of architectural decisions\ncovers all game design requirements, is internally consistent, and correctly targets\nthe project's pinned engine version. It is the quality gate between Technical Setup\nand Pre-Production.\n\n**Argument modes:**\n- **No argument \u002F `full`**: Full review — all phases\n- **`coverage`**: Traceability only — which GDD requirements have no ADR\n- **`consistency`**: Cross-ADR conflict detection only\n- **`engine`**: Engine compatibility audit only\n- **`single-gdd [path]`**: Review architecture coverage for one specific GDD\n- **`rtm`**: Requirements Traceability Matrix — extends the standard matrix\n  to include story file paths and test file paths; outputs\n  `docs\u002Farchitecture\u002Frequirements-traceability.md` with the full\n  GDD requirement → ADR → Story → Test chain. Use in Production phase when\n  stories and tests exist.\n\n---\n\n## Phase 1: Load Everything\n\n### Phase 1a — L0: Summary Scan (fast, low tokens)\n\nBefore reading any full document, use Grep to extract `## Summary` sections\nfrom all GDDs and ADRs:\n\n```\nGrep pattern=\"## Summary\" glob=\"design\u002Fgdd\u002F*.md\" output_mode=\"content\" -A 4\nGrep pattern=\"## Summary\" glob=\"docs\u002Farchitecture\u002Fadr-*.md\" output_mode=\"content\" -A 3\n```\n\nFor `single-gdd [path]` mode: use the target GDD's summary to identify which\nADRs reference the same system (Grep ADRs for the system name), then full-read\nonly those ADRs. Skip full-reading unrelated GDDs entirely.\n\nFor `engine` mode: only full-read ADRs — GDDs are not needed for engine checks.\n\nFor `coverage` or `full` mode: proceed to full-read everything below.\n\n### Phase 1b — L1\u002FL2: Full Document Load\n\nRead all inputs appropriate to the mode:\n\n### Design Documents\n- All in-scope GDDs in `design\u002Fgdd\u002F` — read every file completely\n- `design\u002Fgdd\u002Fsystems-index.md` — the authoritative list of systems\n\n### Architecture Documents\n- All in-scope ADRs in `docs\u002Farchitecture\u002F` — read every file completely\n- `docs\u002Farchitecture\u002Farchitecture.md` if it exists\n\n### Engine Reference\n- `docs\u002Fengine-reference\u002F[engine]\u002FVERSION.md`\n- `docs\u002Fengine-reference\u002F[engine]\u002Fbreaking-changes.md`\n- `docs\u002Fengine-reference\u002F[engine]\u002Fdeprecated-apis.md`\n- All files in `docs\u002Fengine-reference\u002F[engine]\u002Fmodules\u002F`\n\n### Project Standards\n- `.claude\u002Fdocs\u002Ftechnical-preferences.md`\n\nReport a count: \"Loaded [N] GDDs, [M] ADRs, engine: [name + version].\"\n\n**Also read `docs\u002Fconsistency-failures.md`** if it exists. Extract entries with\nDomain matching the systems under review (Architecture, Engine, or any GDD domain\nbeing covered). Surface recurring patterns as a \"Known conflict-prone areas\" note\nat the top of the Phase 4 conflict detection output.\n\n---\n\n## Phase 2: Extract Technical Requirements from Every GDD\n\n### Pre-load the TR Registry\n\nBefore extracting any requirements, read `docs\u002Farchitecture\u002Ftr-registry.yaml`\nif it exists. Index existing entries by `id` and by normalized `requirement`\ntext (lowercase, trimmed). This prevents ID renumbering across review runs.\n\nFor each requirement you extract, the matching rule is:\n1. **Exact\u002Fnear match** to an existing registry entry for the same system →\n   reuse that entry's TR-ID unchanged. Update the `requirement` text in the\n   registry only if the GDD wording changed (same intent, clearer phrasing) —\n   add a `revised: [date]` field.\n2. **No match** → assign a new ID: next available `TR-[system]-NNN` for that\n   system, starting from the highest existing sequence + 1.\n3. **Ambiguous** (partial match, intent unclear) → ask the user:\n   > \"Does '[new requirement text]' refer to the same requirement as\n   > `TR-[system]-NNN: [existing text]'`, or is it a new requirement?\"\n   User answers: \"Same requirement\" (reuse ID) or \"New requirement\" (new ID).\n\nFor any requirement with `status: deprecated` in the registry — skip it.\nIt was removed from the GDD intentionally.\n\nFor each GDD, read it and extract all **technical requirements** — things the\narchitecture must provide for the system to work. A technical requirement is any\nstatement that implies a specific architectural decision.\n\nCategories to extract:\n\n| Category | Example |\n|----------|---------|\n| **Data structures** | \"Each entity has health, max health, status effects\" → needs a component\u002Fdata schema |\n| **Performance constraints** | \"Collision detection must run at 60fps with 200 entities\" → physics budget ADR |\n| **Engine capability** | \"Inverse kinematics for character animation\" → IK system ADR |\n| **Cross-system communication** | \"Damage system notifies UI and audio simultaneously\" → event\u002Fsignal architecture ADR |\n| **State persistence** | \"Player progress persists between sessions\" → save system ADR |\n| **Threading\u002Ftiming** | \"AI decisions happen off the main thread\" → concurrency ADR |\n| **Platform requirements** | \"Supports keyboard, gamepad, touch\" → input system ADR |\n\nFor each GDD, produce a structured list:\n\n```\nGDD: [filename]\nSystem: [system name]\nTechnical Requirements:\n  TR-[GDD]-001: [requirement text] → Domain: [Physics\u002FRendering\u002Fetc]\n  TR-[GDD]-002: [requirement text] → Domain: [...]\n```\n\nThis becomes the **requirements baseline** — the complete set of what the\narchitecture must cover.\n\n---\n\n## Phase 3: Build the Traceability Matrix\n\nFor each technical requirement extracted in Phase 2, search the ADRs:\n\n1. Read every ADR's \"GDD Requirements Addressed\" section\n2. Check if it explicitly references the requirement or its GDD\n3. Check if the ADR's decision text implicitly covers the requirement\n4. Mark coverage status:\n\n| Status | Meaning |\n|--------|---------|\n| ✅ **Covered** | An ADR explicitly addresses this requirement |\n| ⚠️ **Partial** | An ADR partially covers this, or coverage is ambiguous |\n| ❌ **Gap** | No ADR addresses this requirement |\n\nBuild the full matrix:\n\n```\n## Traceability Matrix\n\n| Requirement ID | GDD | System | Requirement | ADR Coverage | Status |\n|---------------|-----|--------|-------------|--------------|--------|\n| TR-combat-001 | combat.md | Combat | Hitbox detection \u003C 1 frame | ADR-0003 | ✅ |\n| TR-combat-002 | combat.md | Combat | Combo window timing | — | ❌ GAP |\n| TR-inventory-001 | inventory.md | Inventory | Persistent item storage | ADR-0005 | ✅ |\n```\n\nCount the totals: X covered, Y partial, Z gaps.\n\n---\n\n## Phase 3b: Story and Test Linkage (RTM mode only)\n\n*Skip this phase unless the argument is `rtm` or `full` with stories present.*\n\nThis phase extends the Phase 3 matrix to include the story that implements\neach requirement and the test that verifies it — producing the full\nRequirements Traceability Matrix (RTM).\n\n### Step 3b-1 — Load stories\n\nGlob `production\u002Fepics\u002F**\u002F*.md` (excluding EPIC.md index files). For each\nstory file:\n- Extract `TR-ID` from the story's Context section\n- Extract story file path, title, Status\n- Extract `## Test Evidence` section — the stated test file path\n\n### Step 3b-2 — Load test files\n\nGlob `tests\u002Funit\u002F**\u002F*_test.*` and `tests\u002Fintegration\u002F**\u002F*_test.*`.\nBuild an index: system → [test file paths].\n\nFor each test file path from Step 3b-1, confirm via Glob whether the file\nactually exists. Note MISSING if the stated path does not exist.\n\n### Step 3b-3 — Build the extended RTM\n\nFor each TR-ID in the Phase 3 matrix, add:\n- **Story**: the story file path(s) that reference this TR-ID (may be multiple)\n- **Test File**: the test file path stated in the story's Test Evidence section\n- **Test Status**: COVERED (test file exists) \u002F MISSING (path stated but not\n  found) \u002F NONE (no test path stated, story type may be Visual\u002FFeel\u002FUI) \u002F\n  NO STORY (requirement has no story yet — pre-production gap)\n\nExtended matrix format:\n\n```\n## Requirements Traceability Matrix (RTM)\n\n| TR-ID | GDD | Requirement | ADR | Story | Test File | Test Status |\n|-------|-----|-------------|-----|-------|-----------|-------------|\n| TR-combat-001 | combat.md | Hitbox \u003C 1 frame | ADR-0003 | story-001-hitbox.md | tests\u002Funit\u002Fcombat\u002Fhitbox_test.gd | COVERED |\n| TR-combat-002 | combat.md | Combo window | — | story-002-combo.md | — | NONE (Visual\u002FFeel) |\n| TR-inventory-001 | inventory.md | Persistent storage | ADR-0005 | — | — | NO STORY |\n```\n\nRTM coverage summary:\n- COVERED: [N] — requirements with ADR + story + passing test\n- MISSING test: [N] — story exists but test file not found\n- NO STORY: [N] — requirements with ADR but no story yet\n- NO ADR: [N] — requirements without architectural coverage (from Phase 3 gaps)\n- Full chain complete (COVERED): [N\u002Ftotal] ([%])\n\n---\n\n## Phase 4: Cross-ADR Conflict Detection\n\nCompare every ADR against every other ADR to detect contradictions. A conflict\nexists when:\n\n- **Data ownership conflict**: Two ADRs claim exclusive ownership of the same data\n- **Integration contract conflict**: ADR-A assumes System X has interface Y, but\n  ADR-B defines System X with a different interface\n- **Performance budget conflict**: ADR-A allocates N ms to physics, ADR-B allocates\n  N ms to AI, together they exceed the total frame budget\n- **Dependency cycle**: ADR-A says System X initialises before Y; ADR-B says Y\n  initialises before X\n- **Architecture pattern conflict**: ADR-A uses event-driven communication for a\n  subsystem; ADR-B uses direct function calls to the same subsystem\n- **State management conflict**: Two ADRs define authority over the same game state\n  (e.g. both Combat ADR and Character ADR claim to own the health value)\n\nFor each conflict found:\n\n```\n## Conflict: [ADR-NNNN] vs [ADR-MMMM]\nType: [Data ownership \u002F Integration \u002F Performance \u002F Dependency \u002F Pattern \u002F State]\nADR-NNNN claims: [...]\nADR-MMMM claims: [...]\nImpact: [What breaks if both are implemented as written]\nResolution options:\n  1. [Option A]\n  2. [Option B]\n```\n\n### ADR Dependency Ordering\n\nAfter conflict detection, analyse the dependency graph across all ADRs:\n\n1. **Collect all `Depends On` fields** from every ADR's \"ADR Dependencies\" section\n2. **Topological sort**: Determine the correct implementation order — ADRs with no\n   dependencies come first (Foundation), ADRs that depend on those come next, etc.\n3. **Flag unresolved dependencies**: If ADR-A's \"Depends On\" field references an ADR\n   that is still `Proposed` or does not exist, flag it:\n   ```\n   ⚠️  ADR-0005 depends on ADR-0002 — but ADR-0002 is still Proposed.\n       ADR-0005 cannot be safely implemented until ADR-0002 is Accepted.\n   ```\n4. **Cycle detection**: If ADR-A depends on ADR-B and ADR-B depends on ADR-A (directly\n   or transitively), flag it as a `DEPENDENCY CYCLE`:\n   ```\n   🔴 DEPENDENCY CYCLE: ADR-0003 → ADR-0006 → ADR-0003\n      This cycle must be broken before either can be implemented.\n   ```\n5. **Output recommended implementation order**:\n   ```\n   ### Recommended ADR Implementation Order (topologically sorted)\n   Foundation (no dependencies):\n     1. ADR-0001: [title]\n     2. ADR-0003: [title]\n   Depends on Foundation:\n     3. ADR-0002: [title] (requires ADR-0001)\n     4. ADR-0005: [title] (requires ADR-0003)\n   Feature layer:\n     5. ADR-0004: [title] (requires ADR-0002, ADR-0005)\n   ```\n\n---\n\n## Phase 5: Engine Compatibility Cross-Check\n\nAcross all ADRs, check for engine consistency:\n\n### Version Consistency\n- Do all ADRs that mention an engine version agree on the same version?\n- If any ADR was written for an older engine version, flag it as potentially stale\n\n### Post-Cutoff API Consistency\n- Collect all \"Post-Cutoff APIs Used\" fields from all ADRs\n- For each, verify against the relevant module reference doc\n- Check that no two ADRs make contradictory assumptions about the same post-cutoff API\n\n### Deprecated API Check\n- Grep all ADRs for API names listed in `deprecated-apis.md`\n- Flag any ADR referencing a deprecated API\n\n### Missing Engine Compatibility Sections\n- List all ADRs that are missing the Engine Compatibility section entirely\n- These are blind spots — their engine assumptions are unknown\n\nOutput format:\n```\n### Engine Audit Results\nEngine: [name + version]\nADRs with Engine Compatibility section: X \u002F Y total\n\nDeprecated API References:\n  - ADR-0002: uses [deprecated API] — deprecated since [version]\n\nStale Version References:\n  - ADR-0001: written for [older version] — current project version is [version]\n\nPost-Cutoff API Conflicts:\n  - ADR-0004 and ADR-0007 both use [API] with incompatible assumptions\n```\n\n---\n\n### Engine Specialist Consultation\n\nAfter completing the engine audit above, spawn the **primary engine specialist** via Task for a domain-expert second opinion:\n- Read `.claude\u002Fdocs\u002Ftechnical-preferences.md` `Engine Specialists` section to get the primary specialist\n- If no engine is configured, skip this consultation\n- 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:\n  1. Confirm or challenge each audit finding — specialists may know of engine nuances not captured in the reference docs\n  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)\n  3. Flag ADRs that make assumptions about engine behaviour that differ from the actual pinned version\n\nIncorporate 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.\n\n---\n\n## Phase 5b: Design Revision Flags (Architecture → GDD Feedback)\n\nFor each **HIGH RISK engine finding** from Phase 5, check whether any GDD makes an\nassumption that the verified engine reality contradicts.\n\nSpecific cases to check:\n\n1. **Post-cutoff API behaviour differs from training-data assumptions**: If an ADR\n   records a verified API behaviour that differs from the default LLM assumption,\n   check all GDDs that reference the related system. Look for design rules written\n   around the old (assumed) behaviour.\n\n2. **Known engine limitations in ADRs**: If an ADR records a known engine limitation\n   (e.g. \"Jolt ignores HingeJoint3D damp\", \"D3D12 is now the default backend\"), check\n   GDDs that design mechanics around the affected feature.\n\n3. **Deprecated API conflicts**: If Phase 5 flagged a deprecated API used in an ADR,\n   check whether any GDD contains mechanics that assume the deprecated API's behaviour.\n\nFor each conflict found, record it in the GDD Revision Flags table:\n\n```\n### GDD Revision Flags (Architecture → Design Feedback)\nThese GDD assumptions conflict with verified engine behaviour or accepted ADRs.\nThe GDD should be revised before its system enters implementation.\n\n| GDD | Assumption | Reality (from ADR\u002Fengine-reference) | Action |\n|-----|-----------|--------------------------------------|--------|\n| combat.md | \"Use HingeJoint3D damp for weapon recoil\" | Jolt ignores damp — ADR-0003 | Revise GDD |\n```\n\nIf no revision flags are found, write: \"No GDD revision flags — all GDD assumptions\nare consistent with verified engine behaviour.\"\n\nAsk: \"Should I flag these GDDs for revision in the systems index?\"\n- If yes: update the relevant systems' Status field to \"Needs Revision\"\n  and add a short inline note in the adjacent Notes\u002FDescription column explaining the conflict.\n  Ask for approval before writing.\n  (Do NOT use parentheticals like \"Needs Revision (Architecture Feedback)\" — other skills\n  match the exact string \"Needs Revision\" and parentheticals break that match.)\n\n---\n\n## Phase 6: Architecture Document Coverage\n\nIf `docs\u002Farchitecture\u002Farchitecture.md` exists, validate it against GDDs:\n\n- Does every system from `systems-index.md` appear in the architecture layers?\n- Does the data flow section cover all cross-system communication defined in GDDs?\n- Do the API boundaries support all integration requirements from GDDs?\n- Are there systems in the architecture doc that have no corresponding GDD\n  (orphaned architecture)?\n\n---\n\n## Phase 7: Output the Review Report\n\n```\n## Architecture Review Report\nDate: [date]\nEngine: [name + version]\nGDDs Reviewed: [N]\nADRs Reviewed: [M]\n\n---\n\n### Traceability Summary\nTotal requirements: [N]\n✅ Covered: [X]\n⚠️ Partial: [Y]\n❌ Gaps: [Z]\n\n### Coverage Gaps (no ADR exists)\nFor each gap:\n  ❌ TR-[id]: [GDD] → [system] → [requirement]\n     Suggested ADR: \"\u002Farchitecture-decision [suggested title]\"\n     Domain: [Physics\u002FRendering\u002Fetc]\n     Engine Risk: [LOW\u002FMEDIUM\u002FHIGH]\n\n### Cross-ADR Conflicts\n[List all conflicts from Phase 4]\n\n### ADR Dependency Order\n[Topologically sorted implementation order from Phase 4 — dependency ordering section]\n[Unresolved dependencies and cycles if any]\n\n### GDD Revision Flags\n[GDD assumptions that conflict with verified engine behaviour — from Phase 5b]\n[Or: \"None — all GDD assumptions consistent with verified engine behaviour\"]\n\n### Engine Compatibility Issues\n[List all engine issues from Phase 5]\n\n### Architecture Document Coverage\n[List missing systems and orphaned architecture from Phase 6]\n\n---\n\n### Verdict: [PASS \u002F CONCERNS \u002F FAIL]\n\nPASS: All requirements covered, no conflicts, engine consistent\nCONCERNS: Some gaps or partial coverage, but no blocking conflicts\nFAIL: Critical gaps (Foundation\u002FCore layer requirements uncovered),\n      or blocking cross-ADR conflicts detected\n\n### Blocking Issues (must resolve before PASS)\n[List items that must be resolved — FAIL verdict only]\n\n### Required ADRs\n[Prioritised list of ADRs to create, most foundational first]\n```\n\n---\n\n## Phase 8: Write and Update Traceability Index\n\nUse `AskUserQuestion` for the write approval:\n- \"Review complete. What would you like to write?\"\n  - [A] Write all three files (review report + traceability index + TR registry)\n  - [B] Write review report only — `docs\u002Farchitecture\u002Farchitecture-review-[date].md`\n  - [C] Don't write anything yet — I need to review the findings first\n\n### RTM Output (rtm mode only)\n\nFor `rtm` mode, additionally ask: \"May I write the full Requirements Traceability\nMatrix to `docs\u002Farchitecture\u002Frequirements-traceability.md`?\"\n\nRTM file format:\n\n```markdown\n# Requirements Traceability Matrix (RTM)\n\n> Last Updated: [date]\n> Mode: \u002Farchitecture-review rtm\n> Coverage: [N]% full chain complete (GDD → ADR → Story → Test)\n\n## How to read this matrix\n\n| Column | Meaning |\n|--------|---------|\n| TR-ID | Stable requirement ID from tr-registry.yaml |\n| GDD | Source design document |\n| ADR | Architectural decision governing implementation |\n| Story | Story file that implements this requirement |\n| Test File | Automated test file path |\n| Test Status | COVERED \u002F MISSING \u002F NONE \u002F NO STORY |\n\n## Full Traceability Matrix\n\n| TR-ID | GDD | Requirement | ADR | Story | Test File | Status |\n|-------|-----|-------------|-----|-------|-----------|--------|\n[Full matrix rows from Phase 3b]\n\n## Coverage Summary\n\n| Status | Count | % |\n|--------|-------|---|\n| COVERED — full chain complete | [N] | [%] |\n| MISSING test — story exists, no test | [N] | [%] |\n| NO STORY — ADR exists, not yet implemented | [N] | [%] |\n| NO ADR — architectural gap | [N] | [%] |\n| **Total requirements** | **[N]** | **100%** |\n\n## Uncovered Requirements (Priority Fix List)\n\nRequirements where the full chain is broken, prioritised by layer:\n\n### Foundation layer gaps\n[list with suggested action per gap]\n\n### Core layer gaps\n[list]\n\n### Feature \u002F Presentation layer gaps\n[list — lower priority]\n\n## History\n\n| Date | Full Chain % | Notes |\n|------|-------------|-------|\n| [date] | [%] | Initial RTM |\n```\n\n### TR Registry Update\n\nAlso ask: \"May I update `docs\u002Farchitecture\u002Ftr-registry.yaml` with new requirement\nIDs from this review?\"\n\nIf yes:\n- **Append** any new TR-IDs that weren't in the registry before this review\n- **Update** `requirement` text and `revised` date for any entries whose GDD\n  wording changed (ID stays the same)\n- **Mark** `status: deprecated` for any registry entries whose GDD requirement\n  no longer exists (confirm with user before marking deprecated)\n- **Never** renumber or delete existing entries\n- Update the `last_updated` and `version` fields at the top\n\nThis ensures all future story files can reference stable TR-IDs that persist\nacross every subsequent architecture review.\n\n### Reflexion Log Update\n\nAfter writing the review report, append any 🔴 CONFLICT entries found in Phase 4\nto `docs\u002Fconsistency-failures.md` (if the file exists):\n\n```markdown\n### [YYYY-MM-DD] — \u002Farchitecture-review — 🔴 CONFLICT\n**Domain**: Architecture \u002F [specific domain e.g. State Ownership, Performance]\n**Documents involved**: [ADR-NNNN] vs [ADR-MMMM]\n**What happened**: [specific conflict — what each ADR claims]\n**Resolution**: [how it was or should be resolved]\n**Pattern**: [generalised lesson for future ADR authors in this domain]\n```\n\nOnly append CONFLICT entries — do not log GAP entries (missing ADRs are expected\nbefore the architecture is complete). Do not create the file if missing — only\nappend when it already exists.\n\n### Session State Update\n\nAfter writing all approved files, silently append to\n`production\u002Fsession-state\u002Factive.md`:\n\n    ## Session Extract — \u002Farchitecture-review [date]\n    - Verdict: [PASS \u002F CONCERNS \u002F FAIL]\n    - Requirements: [N] total — [X] covered, [Y] partial, [Z] gaps\n    - New TR-IDs registered: [N, or \"None\"]\n    - GDD revision flags: [comma-separated GDD names, or \"None\"]\n    - Top ADR gaps: [top 3 gap titles from the report, or \"None\"]\n    - Report: docs\u002Farchitecture\u002Farchitecture-review-[date].md\n\nIf `active.md` does not exist, create it with this block as the initial content.\nConfirm in conversation: \"Session state updated.\"\n\nThe traceability index format:\n\n```markdown\n# Architecture Traceability Index\nLast Updated: [date]\nEngine: [name + version]\n\n## Coverage Summary\n- Total requirements: [N]\n- Covered: [X] ([%])\n- Partial: [Y]\n- Gaps: [Z]\n\n## Full Matrix\n[Complete traceability matrix from Phase 3]\n\n## Known Gaps\n[All ❌ items with suggested ADRs]\n\n## Superseded Requirements\n[Requirements whose GDD was changed after the ADR was written]\n```\n\n---\n\n## Phase 9: Handoff\n\nAfter completing the review and writing approved files, present:\n\n1. **Immediate actions**: List the top 3 ADRs to create (highest-impact gaps first,\n   Foundation layer before Feature layer)\n2. **Gate guidance**: \"When all blocking issues are resolved, run `\u002Fgate-check\n   pre-production` to advance\"\n3. **Rerun trigger**: \"Re-run `\u002Farchitecture-review` after each new ADR is written\n   to verify coverage improves\"\n\nThen close with `AskUserQuestion`:\n- \"Architecture review complete. What would you like to do next?\"\n  - [A] Write a missing ADR — open a fresh session and run `\u002Farchitecture-decision [system]`\n  - [B] Run `\u002Fgate-check pre-production` — if all blocking gaps are resolved\n  - [C] Stop here for this session\n\n---\n\n## Error Recovery Protocol\n\nIf any spawned agent returns BLOCKED, errors, or fails to complete:\n\n1. **Surface immediately**: Report \"[AgentName]: BLOCKED — [reason]\" before continuing\n2. **Assess dependencies**: If the blocked agent's output is required by a later phase, do not proceed past that phase without user input\n3. **Offer options** via AskUserQuestion with three choices:\n   - Skip this agent and note the gap in the final report\n   - Retry with narrower scope (fewer GDDs, single-system focus)\n   - Stop here and resolve the blocker first\n4. **Always produce a partial report** — output whatever was completed so work is not lost\n\n---\n\n## Collaborative Protocol\n\n1. **Read silently** — do not narrate every file read\n2. **Show the matrix** — present the full traceability matrix before asking for\n   anything; let the user see the state\n3. **Don't guess** — if a requirement is ambiguous, ask: \"Is [X] a technical\n   requirement or a design preference?\"\n4. **Ask before writing** — always confirm before writing the report file\n5. **Non-blocking** — the verdict is advisory; the user decides whether to continue\n   despite CONCERNS or even FAIL findings\n","# Architecture Review\n\nThe architecture review validates that the complete body of architectural decisions\ncovers all game design requirements, is internally consistent, and correctly targets\nthe project's pinned engine version. It is the quality gate between Technical Setup\nand Pre-Production.\n\n**Argument modes:**\n- **No argument \u002F `full`**: Full review — all phases\n- **`coverage`**: Traceability only — which GDD requirements have no ADR\n- **`consistency`**: Cross-ADR conflict detection only\n- **`engine`**: Engine compatibility audit only\n- **`single-gdd [path]`**: Review architecture coverage for one specific GDD\n- **`rtm`**: Requirements Traceability Matrix — extends the standard matrix\n  to include story file paths and test file paths; outputs\n  `docs\u002Farchitecture\u002Frequirements-traceability.md` with the full\n  GDD requirement → ADR → Story → Test chain. Use in Production phase when\n  stories and tests exist.\n\n---\n\n## Phase 1: Load Everything\n\n### Phase 1a — L0: Summary Scan (fast, low tokens)\n\nBefore reading any full document, use Grep to extract `## Summary` sections\nfrom all GDDs and ADRs:\n\n```\nGrep pattern=\"## Summary\" glob=\"design\u002Fgdd\u002F*.md\" output_mode=\"content\" -A 4\nGrep pattern=\"## Summary\" glob=\"docs\u002Farchitecture\u002Fadr-*.md\" output_mode=\"content\" -A 3\n```\n\nFor `single-gdd [path]` mode: use the target GDD's summary to identify which\nADRs reference the same system (Grep ADRs for the system name), then full-read\nonly those ADRs. Skip full-reading unrelated GDDs entirely.\n\nFor `engine` mode: only full-read ADRs — GDDs are not needed for engine checks.\n\nFor `coverage` or `full` mode: proceed to full-read everything below.\n\n### Phase 1b — L1\u002FL2: Full Document Load\n\nRead all inputs appropriate to the mode:\n\n### Design Documents\n- All in-scope GDDs in `design\u002Fgdd\u002F` — read every file completely\n- `design\u002Fgdd\u002Fsystems-index.md` — the authoritative list of systems\n\n### Architecture Documents\n- All in-scope ADRs in `docs\u002Farchitecture\u002F` — read every file completely\n- `docs\u002Farchitecture\u002Farchitecture.md` if it exists\n\n### Engine Reference\n- `docs\u002Fengine-reference\u002F[engine]\u002FVERSION.md`\n- `docs\u002Fengine-reference\u002F[engine]\u002Fbreaking-changes.md`\n- `docs\u002Fengine-reference\u002F[engine]\u002Fdeprecated-apis.md`\n- All files in `docs\u002Fengine-reference\u002F[engine]\u002Fmodules\u002F`\n\n### Project Standards\n- `.claude\u002Fdocs\u002Ftechnical-preferences.md`\n\nReport a count: \"Loaded [N] GDDs, [M] ADRs, engine: [name + version].\"\n\n**Also read `docs\u002Fconsistency-failures.md`** if it exists. Extract entries with\nDomain matching the systems under review (Architecture, Engine, or any GDD domain\nbeing covered). Surface recurring patterns as a \"Known conflict-prone areas\" note\nat the top of the Phase 4 conflict detection output.\n\n---\n\n## Phase 2: Extract Technical Requirements from Every GDD\n\n### Pre-load the TR Registry\n\nBefore extracting any requirements, read `docs\u002Farchitecture\u002Ftr-registry.yaml`\nif it exists. Index existing entries by `id` and by normalized `requirement`\ntext (lowercase, trimmed). This prevents ID renumbering across review runs.\n\nFor each requirement you extract, the matching rule is:\n1. **Exact\u002Fnear match** to an existing registry entry for the same system →\n   reuse that entry's TR-ID unchanged. Update the `requirement` text in the\n   registry only if the GDD wording changed (same intent, clearer phrasing) —\n   add a `revised: [date]` field.\n2. **No match** → assign a new ID: next available `TR-[system]-NNN` for that\n   system, starting from the highest existing sequence + 1.\n3. **Ambiguous** (partial match, intent unclear) → ask the user:\n   > \"Does '[new requirement text]' refer to the same requirement as\n   > `TR-[system]-NNN: [existing text]'`, or is it a new requirement?\"\n   User answers: \"Same requirement\" (reuse ID) or \"New requirement\" (new ID).\n\nFor any requirement with `status: deprecated` in the registry — skip it.\nIt was removed from the GDD intentionally.\n\nFor each GDD, read it and extract all **technical requirements** — things the\narchitecture must provide for the system to work. A technical requirement is any\nstatement that implies a specific architectural decision.\n\nCategories to extract:\n\n| Category | Example |\n|----------|---------|\n| **Data structures** | \"Each entity has health, max health, status effects\" → needs a component\u002Fdata schema |\n| **Performance constraints** | \"Collision detection must run at 60fps with 200 entities\" → physics budget ADR |\n| **Engine capability** | \"Inverse kinematics for character animation\" → IK system ADR |\n| **Cross-system communication** | \"Damage system notifies UI and audio simultaneously\" → event\u002Fsignal architecture ADR |\n| **State persistence** | \"Player progress persists between sessions\" → save system ADR |\n| **Threading\u002Ftiming** | \"AI decisions happen off the main thread\" → concurrency ADR |\n| **Platform requirements** | \"Supports keyboard, gamepad, touch\" → input system ADR |\n\nFor each GDD, produce a structured list:\n\n```\nGDD: [filename]\nSystem: [system name]\nTechnical Requirements:\n  TR-[GDD]-001: [requirement text] → Domain: [Physics\u002FRendering\u002Fetc]\n  TR-[GDD]-002: [requirement text] → Domain: [...]\n```\n\nThis becomes the **requirements baseline** — the complete set of what the\narchitecture must cover.\n\n---\n\n## Phase 3: Build the Traceability Matrix\n\nFor each technical requirement extracted in Phase 2, search the ADRs:\n\n1. Read every ADR's \"GDD Requirements Addressed\" section\n2. Check if it explicitly references the requirement or its GDD\n3. Check if the ADR's decision text implicitly covers the requirement\n4. Mark coverage status:\n\n| Status | Meaning |\n|--------|---------|\n| ✅ **Covered** | An ADR explicitly addresses this requirement |\n| ⚠️ **Partial** | An ADR partially covers this, or coverage is ambiguous |\n| ❌ **Gap** | No ADR addresses this requirement |\n\nBuild the full matrix:\n\n```\n## Traceability Matrix\n\n| Requirement ID | GDD | System | Requirement | ADR Coverage | Status |\n|---------------|-----|--------|-------------|--------------|--------|\n| TR-combat-001 | combat.md | Combat | Hitbox detection \u003C 1 frame | ADR-0003 | ✅ |\n| TR-combat-002 | combat.md | Combat | Combo window timing | — | ❌ GAP |\n| TR-inventory-001 | inventory.md | Inventory | Persistent item storage | ADR-0005 | ✅ |\n```\n\nCount the totals: X covered, Y partial, Z gaps.\n\n---\n\n## Phase 3b: Story and Test Linkage (RTM mode only)\n\n*Skip this phase unless the argument is `rtm` or `full` with stories present.*\n\nThis phase extends the Phase 3 matrix to include the story that implements\neach requirement and the test that verifies it — producing the full\nRequirements Traceability Matrix (RTM).\n\n### Step 3b-1 — Load stories\n\nGlob `production\u002Fepics\u002F**\u002F*.md` (excluding EPIC.md index files). For each\nstory file:\n- Extract `TR-ID` from the story's Context section\n- Extract story file path, title, Status\n- Extract `## Test Evidence` section — the stated test file path\n\n### Step 3b-2 — Load test files\n\nGlob `tests\u002Funit\u002F**\u002F*_test.*` and `tests\u002Fintegration\u002F**\u002F*_test.*`.\nBuild an index: system → [test file paths].\n\nFor each test file path from Step 3b-1, confirm via Glob whether the file\nactually exists. Note MISSING if the stated path does not exist.\n\n### Step 3b-3 — Build the extended RTM\n\nFor each TR-ID in the Phase 3 matrix, add:\n- **Story**: the story file path(s) that reference this TR-ID (may be multiple)\n- **Test File**: the test file path stated in the story's Test Evidence section\n- **Test Status**: COVERED (test file exists) \u002F MISSING (path stated but not\n  found) \u002F NONE (no test path stated, story type may be Visual\u002FFeel\u002FUI) \u002F\n  NO STORY (requirement has no story yet — pre-production gap)\n\nExtended matrix format:\n\n```\n## Requirements Traceability Matrix (RTM)\n\n| TR-ID | GDD | Requirement | ADR | Story | Test File | Test Status |\n|-------|-----|-------------|-----|-------|-----------|-------------|\n| TR-combat-001 | combat.md | Hitbox \u003C 1 frame | ADR-0003 | story-001-hitbox.md | tests\u002Funit\u002Fcombat\u002Fhitbox_test.gd | COVERED |\n| TR-combat-002 | combat.md | Combo window | — | story-002-combo.md | — | NONE (Visual\u002FFeel) |\n| TR-inventory-001 | inventory.md | Persistent storage | ADR-0005 | — | — | NO STORY |\n```\n\nRTM coverage summary:\n- COVERED: [N] — requirements with ADR + story + passing test\n- MISSING test: [N] — story exists but test file not found\n- NO STORY: [N] — requirements with ADR but no story yet\n- NO ADR: [N] — requirements without architectural coverage (from Phase 3 gaps)\n- Full chain complete (COVERED): [N\u002Ftotal] ([%])\n\n---\n\n## Phase 4: Cross-ADR Conflict Detection\n\nCompare every ADR against every other ADR to detect contradictions. A conflict\nexists when:\n\n- **Data ownership conflict**: Two ADRs claim exclusive ownership of the same data\n- **Integration contract conflict**: ADR-A assumes System X has interface Y, but\n  ADR-B defines System X with a different interface\n- **Performance budget conflict**: ADR-A allocates N ms to physics, ADR-B allocates\n  N ms to AI, together they exceed the total frame budget\n- **Dependency cycle**: ADR-A says System X initialises before Y; ADR-B says Y\n  initialises before X\n- **Architecture pattern conflict**: ADR-A uses event-driven communication for a\n  subsystem; ADR-B uses direct function calls to the same subsystem\n- **State management conflict**: Two ADRs define authority over the same game state\n  (e.g. both Combat ADR and Character ADR claim to own the health value)\n\nFor each conflict found:\n\n```\n## Conflict: [ADR-NNNN] vs [ADR-MMMM]\nType: [Data ownership \u002F Integration \u002F Performance \u002F Dependency \u002F Pattern \u002F State]\nADR-NNNN claims: [...]\nADR-MMMM claims: [...]\nImpact: [What breaks if both are implemented as written]\nResolution options:\n  1. [Option A]\n  2. [Option B]\n```\n\n### ADR Dependency Ordering\n\nAfter conflict detection, analyse the dependency graph across all ADRs:\n\n1. **Collect all `Depends On` fields** from every ADR's \"ADR Dependencies\" section\n2. **Topological sort**: Determine the correct implementation order — ADRs with no\n   dependencies come first (Foundation), ADRs that depend on those come next, etc.\n3. **Flag unresolved dependencies**: If ADR-A's \"Depends On\" field references an ADR\n   that is still `Proposed` or does not exist, flag it:\n   ```\n   ⚠️  ADR-0005 depends on ADR-0002 — but ADR-0002 is still Proposed.\n       ADR-0005 cannot be safely implemented until ADR-0002 is Accepted.\n   ```\n4. **Cycle detection**: If ADR-A depends on ADR-B and ADR-B depends on ADR-A (directly\n   or transitively), flag it as a `DEPENDENCY CYCLE`:\n   ```\n   🔴 DEPENDENCY CYCLE: ADR-0003 → ADR-0006 → ADR-0003\n      This cycle must be broken before either can be implemented.\n   ```\n5. **Output recommended implementation order**:\n   ```\n   ### Recommended ADR Implementation Order (topologically sorted)\n   Foundation (no dependencies):\n     1. ADR-0001: [title]\n     2. ADR-0003: [title]\n   Depends on Foundation:\n     3. ADR-0002: [title] (requires ADR-0001)\n     4. ADR-0005: [title] (requires ADR-0003)\n   Feature layer:\n     5. ADR-0004: [title] (requires ADR-0002, ADR-0005)\n   ```\n\n---\n\n## Phase 5: Engine Compatibility Cross-Check\n\nAcross all ADRs, check for engine consistency:\n\n### Version Consistency\n- Do all ADRs that mention an engine version agree on the same version?\n- If any ADR was written for an older engine version, flag it as potentially stale\n\n### Post-Cutoff API Consistency\n- Collect all \"Post-Cutoff APIs Used\" fields from all ADRs\n- For each, verify against the relevant module reference doc\n- Check that no two ADRs make contradictory assumptions about the same post-cutoff API\n\n### Deprecated API Check\n- Grep all ADRs for API names listed in `deprecated-apis.md`\n- Flag any ADR referencing a deprecated API\n\n### Missing Engine Compatibility Sections\n- List all ADRs that are missing the Engine Compatibility section entirely\n- These are blind spots — their engine assumptions are unknown\n\nOutput format:\n```\n### Engine Audit Results\nEngine: [name + version]\nADRs with Engine Compatibility section: X \u002F Y total\n\nDeprecated API References:\n  - ADR-0002: uses [deprecated API] — deprecated since [version]\n\nStale Version References:\n  - ADR-0001: written for [older version] — current project version is [version]\n\nPost-Cutoff API Conflicts:\n  - ADR-0004 and ADR-0007 both use [API] with incompatible assumptions\n```\n\n---\n\n### Engine Specialist Consultation\n\nAfter completing the engine audit above, spawn the **primary engine specialist** via Task for a domain-expert second opinion:\n- Read `.claude\u002Fdocs\u002Ftechnical-preferences.md` `Engine Specialists` section to get the primary specialist\n- If no engine is configured, skip this consultation\n- 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:\n  1. Confirm or challenge each audit finding — specialists may know of engine nuances not captured in the reference docs\n  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)\n  3. Flag ADRs that make assumptions about engine behaviour that differ from the actual pinned version\n\nIncorporate 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.\n\n---\n\n## Phase 5b: Design Revision Flags (Architecture → GDD Feedback)\n\nFor each **HIGH RISK engine finding** from Phase 5, check whether any GDD makes an\nassumption that the verified engine reality contradicts.\n\nSpecific cases to check:\n\n1. **Post-cutoff API behaviour differs from training-data assumptions**: If an ADR\n   records a verified API behaviour that differs from the default LLM assumption,\n   check all GDDs that reference the related system. Look for design rules written\n   around the old (assumed) behaviour.\n\n2. **Known engine limitations in ADRs**: If an ADR records a known engine limitation\n   (e.g. \"Jolt ignores HingeJoint3D damp\", \"D3D12 is now the default backend\"), check\n   GDDs that design mechanics around the affected feature.\n\n3. **Deprecated API conflicts**: If Phase 5 flagged a deprecated API used in an ADR,\n   check whether any GDD contains mechanics that assume the deprecated API's behaviour.\n\nFor each conflict found, record it in the GDD Revision Flags table:\n\n```\n### GDD Revision Flags (Architecture → Design Feedback)\nThese GDD assumptions conflict with verified engine behaviour or accepted ADRs.\nThe GDD should be revised before its system enters implementation.\n\n| GDD | Assumption | Reality (from ADR\u002Fengine-reference) | Action |\n|-----|-----------|--------------------------------------|--------|\n| combat.md | \"Use HingeJoint3D damp for weapon recoil\" | Jolt ignores damp — ADR-0003 | Revise GDD |\n```\n\nIf no revision flags are found, write: \"No GDD revision flags — all GDD assumptions\nare consistent with verified engine behaviour.\"\n\nAsk: \"Should I flag these GDDs for revision in the systems index?\"\n- If yes: update the relevant systems' Status field to \"Needs Revision\"\n  and add a short inline note in the adjacent Notes\u002FDescription column explaining the conflict.\n  Ask for approval before writing.\n  (Do NOT use parentheticals like \"Needs Revision (Architecture Feedback)\" — other skills\n  match the exact string \"Needs Revision\" and parentheticals break that match.)\n\n---\n\n## Phase 6: Architecture Document Coverage\n\nIf `docs\u002Farchitecture\u002Farchitecture.md` exists, validate it against GDDs:\n\n- Does every system from `systems-index.md` appear in the architecture layers?\n- Does the data flow section cover all cross-system communication defined in GDDs?\n- Do the API boundaries support all integration requirements from GDDs?\n- Are there systems in the architecture doc that have no corresponding GDD\n  (orphaned architecture)?\n\n---\n\n## Phase 7: Output the Review Report\n\n```\n## Architecture Review Report\nDate: [date]\nEngine: [name + version]\nGDDs Reviewed: [N]\nADRs Reviewed: [M]\n\n---\n\n### Traceability Summary\nTotal requirements: [N]\n✅ Covered: [X]\n⚠️ Partial: [Y]\n❌ Gaps: [Z]\n\n### Coverage Gaps (no ADR exists)\nFor each gap:\n  ❌ TR-[id]: [GDD] → [system] → [requirement]\n     Suggested ADR: \"\u002Farchitecture-decision [suggested title]\"\n     Domain: [Physics\u002FRendering\u002Fetc]\n     Engine Risk: [LOW\u002FMEDIUM\u002FHIGH]\n\n### Cross-ADR Conflicts\n[List all conflicts from Phase 4]\n\n### ADR Dependency Order\n[Topologically sorted implementation order from Phase 4 — dependency ordering section]\n[Unresolved dependencies and cycles if any]\n\n### GDD Revision Flags\n[GDD assumptions that conflict with verified engine behaviour — from Phase 5b]\n[Or: \"None — all GDD assumptions consistent with verified engine behaviour\"]\n\n### Engine Compatibility Issues\n[List all engine issues from Phase 5]\n\n### Architecture Document Coverage\n[List missing systems and orphaned architecture from Phase 6]\n\n---\n\n### Verdict: [PASS \u002F CONCERNS \u002F FAIL]\n\nPASS: All requirements covered, no conflicts, engine consistent\nCONCERNS: Some gaps or partial coverage, but no blocking conflicts\nFAIL: Critical gaps (Foundation\u002FCore layer requirements uncovered),\n      or blocking cross-ADR conflicts detected\n\n### Blocking Issues (must resolve before PASS)\n[List items that must be resolved — FAIL verdict only]\n\n### Required ADRs\n[Prioritised list of ADRs to create, most foundational first]\n```\n\n---\n\n## Phase 8: Write and Update Traceability Index\n\nUse `AskUserQuestion` for the write approval:\n- \"Review complete. What would you like to write?\"\n  - [A] Write all three files (review report + traceability index + TR registry)\n  - [B] Write review report only — `docs\u002Farchitecture\u002Farchitecture-review-[date].md`\n  - [C] Don't write anything yet — I need to review the findings first\n\n### RTM Output (rtm mode only)\n\nFor `rtm` mode, additionally ask: \"May I write the full Requirements Traceability\nMatrix to `docs\u002Farchitecture\u002Frequirements-traceability.md`?\"\n\nRTM file format:\n\n```markdown\n# Requirements Traceability Matrix (RTM)\n\n> Last Updated: [date]\n> Mode: \u002Farchitecture-review rtm\n> Coverage: [N]% full chain complete (GDD → ADR → Story → Test)\n\n## How to read this matrix\n\n| Column | Meaning |\n|--------|---------|\n| TR-ID | Stable requirement ID from tr-registry.yaml |\n| GDD | Source design document |\n| ADR | Architectural decision governing implementation |\n| Story | Story file that implements this requirement |\n| Test File | Automated test file path |\n| Test Status | COVERED \u002F MISSING \u002F NONE \u002F NO STORY |\n\n## Full Traceability Matrix\n\n| TR-ID | GDD | Requirement | ADR | Story | Test File | Status |\n|-------|-----|-------------|-----|-------|-----------|--------|\n[Full matrix rows from Phase 3b]\n\n## Coverage Summary\n\n| Status | Count | % |\n|--------|-------|---|\n| COVERED — full chain complete | [N] | [%] |\n| MISSING test — story exists, no test | [N] | [%] |\n| NO STORY — ADR exists, not yet implemented | [N] | [%] |\n| NO ADR — architectural gap | [N] | [%] |\n| **Total requirements** | **[N]** | **100%** |\n\n## Uncovered Requirements (Priority Fix List)\n\nRequirements where the full chain is broken, prioritised by layer:\n\n### Foundation layer gaps\n[list with suggested action per gap]\n\n### Core layer gaps\n[list]\n\n### Feature \u002F Presentation layer gaps\n[list — lower priority]\n\n## History\n\n| Date | Full Chain % | Notes |\n|------|-------------|-------|\n| [date] | [%] | Initial RTM |\n```\n\n### TR Registry Update\n\nAlso ask: \"May I update `docs\u002Farchitecture\u002Ftr-registry.yaml` with new requirement\nIDs from this review?\"\n\nIf yes:\n- **Append** any new TR-IDs that weren't in the registry before this review\n- **Update** `requirement` text and `revised` date for any entries whose GDD\n  wording changed (ID stays the same)\n- **Mark** `status: deprecated` for any registry entries whose GDD requirement\n  no longer exists (confirm with user before marking deprecated)\n- **Never** renumber or delete existing entries\n- Update the `last_updated` and `version` fields at the top\n\nThis ensures all future story files can reference stable TR-IDs that persist\nacross every subsequent architecture review.\n\n### Reflexion Log Update\n\nAfter writing the review report, append any 🔴 CONFLICT entries found in Phase 4\nto `docs\u002Fconsistency-failures.md` (if the file exists):\n\n```markdown\n### [YYYY-MM-DD] — \u002Farchitecture-review — 🔴 CONFLICT\n**Domain**: Architecture \u002F [specific domain e.g. State Ownership, Performance]\n**Documents involved**: [ADR-NNNN] vs [ADR-MMMM]\n**What happened**: [specific conflict — what each ADR claims]\n**Resolution**: [how it was or should be resolved]\n**Pattern**: [generalised lesson for future ADR authors in this domain]\n```\n\nOnly append CONFLICT entries — do not log GAP entries (missing ADRs are expected\nbefore the architecture is complete). Do not create the file if missing — only\nappend when it already exists.\n\n### Session State Update\n\nAfter writing all approved files, silently append to\n`production\u002Fsession-state\u002Factive.md`:\n\n    ## Session Extract — \u002Farchitecture-review [date]\n    - Verdict: [PASS \u002F CONCERNS \u002F FAIL]\n    - Requirements: [N] total — [X] covered, [Y] partial, [Z] gaps\n    - New TR-IDs registered: [N, or \"None\"]\n    - GDD revision flags: [comma-separated GDD names, or \"None\"]\n    - Top ADR gaps: [top 3 gap titles from the report, or \"None\"]\n    - Report: docs\u002Farchitecture\u002Farchitecture-review-[date].md\n\nIf `active.md` does not exist, create it with this block as the initial content.\nConfirm in conversation: \"Session state updated.\"\n\nThe traceability index format:\n\n```markdown\n# Architecture Traceability Index\nLast Updated: [date]\nEngine: [name + version]\n\n## Coverage Summary\n- Total requirements: [N]\n- Covered: [X] ([%])\n- Partial: [Y]\n- Gaps: [Z]\n\n## Full Matrix\n[Complete traceability matrix from Phase 3]\n\n## Known Gaps\n[All ❌ items with suggested ADRs]\n\n## Superseded Requirements\n[Requirements whose GDD was changed after the ADR was written]\n```\n\n---\n\n## Phase 9: Handoff\n\nAfter completing the review and writing approved files, present:\n\n1. **Immediate actions**: List the top 3 ADRs to create (highest-impact gaps first,\n   Foundation layer before Feature layer)\n2. **Gate guidance**: \"When all blocking issues are resolved, run `\u002Fgate-check\n   pre-production` to advance\"\n3. **Rerun trigger**: \"Re-run `\u002Farchitecture-review` after each new ADR is written\n   to verify coverage improves\"\n\nThen close with `AskUserQuestion`:\n- \"Architecture review complete. What would you like to do next?\"\n  - [A] Write a missing ADR — open a fresh session and run `\u002Farchitecture-decision [system]`\n  - [B] Run `\u002Fgate-check pre-production` — if all blocking gaps are resolved\n  - [C] Stop here for this session\n\n---\n\n## Error Recovery Protocol\n\nIf any spawned agent returns BLOCKED, errors, or fails to complete:\n\n1. **Surface immediately**: Report \"[AgentName]: BLOCKED — [reason]\" before continuing\n2. **Assess dependencies**: If the blocked agent's output is required by a later phase, do not proceed past that phase without user input\n3. **Offer options** via AskUserQuestion with three choices:\n   - Skip this agent and note the gap in the final report\n   - Retry with narrower scope (fewer GDDs, single-system focus)\n   - Stop here and resolve the blocker first\n4. **Always produce a partial report** — output whatever was completed so work is not lost\n\n---\n\n## Collaborative Protocol\n\n1. **Read silently** — do not narrate every file read\n2. **Show the matrix** — present the full traceability matrix before asking for\n   anything; let the user see the state\n3. **Don't guess** — if a requirement is ambiguous, ask: \"Is [X] a technical\n   requirement or a design preference?\"\n4. **Ask before writing** — always confirm before writing the report file\n5. **Non-blocking** — the verdict is advisory; the user decides whether to continue\n   despite CONCERNS or even FAIL findings\n",{"name":5,"agent":24,"model":25,"description":7,"allowed-tools":26,"argument-hint":27,"user-invocable":28},"technical-director","opus","Read, Glob, Grep, Write, Task, AskUserQuestion","[focus: full | coverage | consistency | engine | single-gdd path\u002Fto\u002Fgdd.md]",true,"main","d69096e239f2a89aabc2cd078c47664a9d3b1e11","05-技能与代理开发\u002Farchitecture-review",3,"https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts","https:\u002F\u002Fgithub.com\u002Flza6","个人vx：Tf00798\r\n个人✈：@TFGY999","2026-10-08 14:29:22",{"source":8,"skillName":5,"commands":38,"prompt":48,"zipAvailable":28},[39,42,45],{"tool":40,"command":41},"npx","npx skills add lza6\u002FArmor-piercing-system-prompts --skill architecture-review",{"tool":43,"command":44},"bunx","bunx skills add lza6\u002FArmor-piercing-system-prompts --skill architecture-review",{"tool":46,"command":47},"pnpm","pnpm dlx skills add lza6\u002FArmor-piercing-system-prompts --skill architecture-review","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F05-技能与代理开发\u002Farchitecture-review\u002FSKILL.md",[],[51,59,64,71,78,85],{"skillNo":52,"name":53,"nameZh":6,"description":54,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":55,"categories":56,"keywords":57,"publishedAt":58},"01M7FFG485KY83TD6HSC4YPCMC","obsidian-clipper-template-creator","Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.","https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F07-后端与架构\u002Fobsidian-clipper-template-creator\u002FSKILL.md",[],[],"2026-11-16 10:05:34",{"skillNo":60,"name":53,"nameZh":6,"description":54,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":61,"categories":62,"keywords":63,"publishedAt":58},"01M7FFG0T6AZ0STEJPSB3CX84K","https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F07-后端与架构\u002Fobsidian-clipper-template-creator-antigravity-awesome-skills-main\u002FSKILL.md",[],[],{"skillNo":65,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":68,"categories":69,"keywords":70,"publishedAt":58},"01M7FFFY0QEM14SKWPDYGMXM2P","python-api","Programmatic Object-Detection-Metrics API guidance for BoundingBox, BoundingBoxes, Evaluator, enums, coordinate conversion, AP\u002FmAP semantics, and source-style import diagnostics.","https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F07-后端与架构\u002Fobject-detection-metrics\u002Fsub-skills\u002Fpython-api\u002FSKILL.md",[],[],{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":58},"01M7FFFVZQZ2GJ0C0TGP7JHD20","file-evaluation","Folder-based PASCAL VOC AP\u002FmAP evaluation from ground-truth and detection text files.","https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F07-后端与架构\u002Fobject-detection-metrics\u002Fsub-skills\u002Ffile-evaluation\u002FSKILL.md",[],[],{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":58},"01M7FFFSFNYSE77SJ6PE1CK2DA","object-detection-metrics","Guides legacy Object-Detection-Metrics PASCAL VOC AP\u002FmAP evaluation from detection text folders and direct Python API classes.","https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F07-后端与架构\u002Fobject-detection-metrics\u002FSKILL.md",[],[],{"skillNo":86,"name":87,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":91,"publishedAt":58},"01M7FFFP0GCK1RVXBCPQ8APBMT","nx-workspace-patterns","Configure and optimize Nx monorepo workspaces. Use when setting up Nx, configuring project boundaries, optimizing build caching, or implementing affected commands.","https:\u002F\u002Fgithub.com\u002Flza6\u002FArmor-piercing-system-prompts\u002Fblob\u002Fmain\u002F07-后端与架构\u002Fnx-workspace-patterns\u002FSKILL.md",[],[]]