Claude-Code-Game-Studios/CCGS Skill Testing Framework/skills/review/architecture-review.md

Skill Test Spec: /architecture-review

Skill Summary

/architecture-review is an Opus-tier skill that checks whether the whole body of architectural decisions covers the game's design. It extracts technical requirements (TR-IDs) from every GDD, maps each one to the ADRs that cover it in a traceability matrix, detects cross-ADR conflicts, orders ADRs by dependency (via .claude/scripts/adr-dep-graph.sh), audits engine compatibility against docs/engine-reference/, consults the primary engine specialist, and checks docs/architecture/architecture.md coverage of the systems index. It produces a PASS / CONCERNS / NOT ASSESSED / FAIL verdict.

It takes a focus argument (full by default, or coverage, consistency, engine, single-gdd [path], rtm). After the report, it asks via AskUserQuestion before writing the review report (docs/architecture/architecture-review-[date].md), the traceability index and docs/architecture/tr-registry.yaml. It is the quality gate between Technical Setup and Pre-Production.

---

Static Assertions (Structural)

Checked against the SKILL.md by /skill-test spec — no fixture needed.

• Has required frontmatter fields: name, description, argument-hint, user-invocable, allowed-tools
• Has ≥2 phase headings
• Contains verdict keywords: PASS, CONCERNS, NOT ASSESSED, FAIL
• allowed-tools includes Write, so write-approval language is present ("May I update the systems index?", "May I update docs/architecture/tr-registry.yaml…")
• Has a next-step handoff at the end (Phase 9)
• Documents the argument modes: full, coverage, consistency, engine, single-gdd [path], rtm

---

Director Gate Checks

None. This skill resolves no review_mode (its config block requests only automation and workflow) and spawns no director gate. The only agent it spawns is the primary engine specialist in Phase 5. The architecture sign-off gates (TD-ARCHITECTURE, LP-FEASIBILITY) belong to /create-architecture, not to this skill.

---

Test Cases

Case 1: Happy Path — every requirement covered by an Accepted ADR

Fixture:

• project.yaml sets modes.workflow: full, engine.name: Godot, engine.version: 4.6
• design/gdd/systems-index.md plus two system GDDs (combat.md, inventory.md), each with a ## Summary and technical requirements in its Detailed Rules
• docs/architecture/adr-0001-*.md … adr-0003-*.md, each with ## Status: Accepted, ## GDD Requirements Addressed, ## Engine Compatibility and ## ADR Dependencies, whose **Depends On** row is filled in — None for adr-0001, ADR-0001 for adr-0002 and adr-0003 — so adr-dep-graph.sh finds real edges and lists no ADR under NO_DEPS_SECTION; together they cover every requirement; no two contradict
• docs/architecture/architecture.md exists and names every system in the index
• No prior docs/architecture/architecture-review-*.md report
• Pre-gate items all exist: tests/unit/, tests/integration/ (the Godot test root), .github/workflows/tests.yml, design/accessibility-requirements.md, design/ux/interaction-patterns.md

Input: /architecture-review

Expected behavior:

1. Freshness check prints RECEIPT: NONE → full review
2. Skill counts the denominators (N_gdd, N_adr), loads the needed sections with targeted Greps rather than whole files, and reports "Loaded [N] GDDs, [M] ADRs, engine: Godot 4.6"
3. Skill extracts TR-IDs (reusing any existing tr-registry.yaml IDs) and builds the matrix
4. Skill runs bash .claude/scripts/adr-dep-graph.sh and prints the recommended implementation order
5. Skill runs the engine audit and consults godot-specialist
6. Report ends with ### Verdict: PASS
7. Phase 8 asks what to write; Phase 9 offers /gate-check pre-production

Assertions:

• Output reports "Loaded [N] GDDs, [M] ADRs, engine: [name + version]"
• A Traceability Matrix lists each TR-ID with its GDD, system, requirement, ADR coverage and status; every row is ✅
• The ADR dependency order comes from adr-dep-graph.sh, not hand-tracing, and puts adr-0001 first; NO_DEPS_SECTION is empty, so the acyclic result is a clean graph rather than a structural gap
• Verdict is PASS only because all requirements are covered by Accepted ADRs, no conflicts exist, and engine references agree
• The report includes the review-receipts.sh hash lines for the ADRs and GDDs reviewed
• No file is written before the Phase 8 AskUserQuestion ([A] all three files / [B] report only at docs/architecture/architecture-review-[date].md / [C] nothing yet)
• The closing widget offers /gate-check pre-production, because every pre-gate checklist item is ✅

---

Case 2: Failure Path — Foundation gap plus a cross-ADR ownership conflict

Fixture:

• As Case 1, except:
  • save-system.md (a Foundation-layer system) requires "Player progress persists between sessions" and no ADR addresses it
  • adr-0002 and adr-0004 are both Accepted and both claim authority over the player's health value

Input: /architecture-review

Expected behavior:

1. The persistence requirement appears as a ❌ GAP row
2. The gap appears under "Coverage Gaps" with a suggested /architecture-decision [title], Domain and Engine Risk
3. A conflict block ## Conflict: [ADR-0002] vs [ADR-0004] is printed
4. Verdict is FAIL; Blocking Issues list at least the Foundation gap
5. Neither ADR is edited; the user decides the resolution

Assertions:

• Verdict is FAIL (a Foundation-layer requirement is uncovered)
• The gap row names the TR-ID, GDD and requirement, with a suggested /architecture-decision command
• The conflict block names both ADR numbers, a Type (State / Data ownership), what each ADR claims, the Impact, and at least two resolution options
• Skill does NOT auto-resolve the conflict or edit either ADR
• If docs/consistency-failures.md exists, the Phase 8 [A] option names it ("…and append 1 conflict entry to docs/consistency-failures.md") and the entry is appended only when the user picks [A]; [B] (report only) writes the report and nothing else; if the file does not exist, it is not created
• The closing widget does not offer /gate-check; it offers writing the missing ADR via /architecture-decision [system]

---

Case 3: Partial Path — coverage resting on a Proposed ADR

Fixture:

• As Case 1, except adr-0003 (the only ADR covering TR-inventory-001) has ## Status: Proposed
• adr-0004 (Accepted) has **Depends On**: ADR-0003 in its ## ADR Dependencies table

Input: /architecture-review

Expected behavior:

1. TR-inventory-001 is marked 🟡 Covered (Proposed), not ✅
2. The dependency analysis flags "ADR-0004 depends on ADR-0003 — but ADR-0003 is still Proposed"
3. Verdict is capped at CONCERNS and names the way out: /architecture-decision accept ADR-0003

Assertions:

• Skill reads each ADR's ## Status before marking coverage; a Proposed ADR never yields ✅
• Verdict is CONCERNS (not PASS) when coverage rests on a Proposed ADR
• Output names /architecture-decision accept ADR-0003 as the route to clear it
• The unresolved dependency on a Proposed ADR is flagged

---

Case 4: Edge Case — missing architecture document; malformed ADRs

Case 4a — no master architecture document:

• As Case 1, but docs/architecture/architecture.md does not exist

Assertions (4a):

• The report states Architecture document coverage: NOT ASSESSED — no docs/architecture/architecture.md as a named line item, rather than showing no Phase 6 findings
• The overall verdict is NOT ASSESSED, not PASS: Phase 6 is part of the full scope and did not run, even though every requirement is covered (a CONCERNS or FAIL finding elsewhere would still outrank it)

Case 4b — ADRs present but none has a scannable section:

• As Case 1 (modes.workflow: full — at the default minimal tier, a project.yaml with no modes block, the skill does not apply), except the three docs/architecture/adr-*.md files carry none of the six headings the Phase 1b scan looks for: ## Status, ## Decision, ## GDD Requirements Addressed, ## Engine Compatibility, ## ADR Dependencies, ## Performance Implications

Assertions (4b):

• Skill reports "[N] ADRs found, none carries a scannable section — run /architecture-decision retrofit [file] on each" (subcommand first — with the path first, /architecture-decision would start authoring a new ADR instead)
• Skill does NOT report zero coverage or a design failure — it is a format failure
• Rows whose ADR has no ## Status are ❓ Not assessed, and the verdict is not PASS — nor FAIL on coverage grounds, since coverage is unknown rather than absent

---

Case 5: Engine specialist consultation — configured vs unconfigured engine

Case 5a — engine configured: Case 1 fixture (engine.name: Godot)

Expected behavior:

1. After the Phase 5 engine audit, skill spawns godot-specialist via Agent, passing the engine-specific ADRs, the engine reference docs and the audit findings
2. The specialist's findings appear under ### Engine Specialist Findings and count toward the verdict

Assertions (5a):

• The specialist is resolved from engine.name (Godot → godot-specialist)
• It is spawned after the engine audit, with the audit findings in its prompt
• Output includes an ### Engine Specialist Findings section
• No director gate (TD-ARCHITECTURE, LP-FEASIBILITY or any other gate ID) is spawned or mentioned

Case 5b — no engine configured: as Case 1, except engine.name is unset in project.yaml and technical-preferences.md is still [TO BE CONFIGURED]

Assertions (5b):

• No engine specialist is spawned
• Output records Engine validation: NOT ASSESSED — no engine configured rather than omitting the step
• The verdict is NOT ASSESSED, not PASS — the engine audit is part of the full scope and had no pinned engine to check against, even though every requirement is covered

---

Protocol Compliance

• Shows the full traceability matrix before any write approval (the Phase 1a freshness question and Phase 2's ambiguous-requirement questions may come earlier)
• Every write approval uses AskUserQuestion with labelled options, not a plain-text "May I?"
• Shows the content to be written (report, systems-index rows) before asking to write it
• Never renumbers or deletes existing tr-registry.yaml entries; marking one deprecated is confirmed with the user
• Verdict is one of exactly: PASS, CONCERNS, NOT ASSESSED, FAIL
• Ends with a Phase 9 handoff via AskUserQuestion; /gate-check is not offered while any pre-gate item is ❌

---

Coverage Notes

• The coverage, consistency, engine, single-gdd and rtm modes are not individually fixture-tested; Cases 1–5 exercise the default full mode.
• Phase 5b (GDD revision flags written to systems-index.md as Needs Revision) is not tested; it needs a HIGH RISK engine finding that contradicts a GDD.
• The freshness receipt paths (everything UNCHANGED, some CHANGED/NEW, UNRESOLVED) are not fixture-tested.
• The standard tier's reduced scope (architecture doc + critical ADRs only) is not tested.
• The default minimal tier (a project.yaml with no modes block), where the skill's scope table says the review does not apply, is not fixture-tested — every case pins modes.workflow: full. Nor is workflow_overrides.system_overrides: this skill does not request that key, so a per-system tier has no effect on it.