添加 claude code game studios 到项目
This commit is contained in:
panw
665
.claude/skills/architecture-review/SKILL.md
Normal file
665
.claude/skills/architecture-review/SKILL.md
Normal file
@@ -0,0 +1,665 @@
|
||||
---
|
||||
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:
|
||||
1. **Exact/near match** to an existing registry entry for the same system →
|
||||
reuse that entry's TR-ID unchanged. Update the `requirement` text in the
|
||||
registry only if the GDD wording changed (same intent, clearer phrasing) —
|
||||
add a `revised: [date]` field.
|
||||
2. **No match** → assign a new ID: next available `TR-[system]-NNN` for that
|
||||
system, starting from the highest existing sequence + 1.
|
||||
3. **Ambiguous** (partial match, intent unclear) → ask the user:
|
||||
> "Does '[new requirement text]' refer to the same requirement as
|
||||
> `TR-[system]-NNN: [existing text]'`, or is it a new requirement?"
|
||||
User answers: "Same requirement" (reuse ID) or "New requirement" (new ID).
|
||||
|
||||
For any requirement with `status: deprecated` in the registry — skip it.
|
||||
It was removed from the GDD intentionally.
|
||||
|
||||
For each GDD, read it and extract all **technical requirements** — things the
|
||||
architecture must provide for the system to work. A technical requirement is any
|
||||
statement that implies a specific architectural decision.
|
||||
|
||||
Categories to extract:
|
||||
|
||||
| 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:
|
||||
|
||||
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:
|
||||
|
||||
| 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:
|
||||
|
||||
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)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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:
|
||||
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
|
||||
|
||||
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:
|
||||
|
||||
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.
|
||||
|
||||
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`.
|
||||
|
||||
---
|
||||
|
||||
## Phase 6: Architecture Document Coverage
|
||||
|
||||
If `docs/architecture/architecture.md` exists, validate it against GDDs:
|
||||
|
||||
- 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)?
|
||||
|
||||
---
|
||||
|
||||
## Phase 7: Output the Review Report
|
||||
|
||||
```
|
||||
## Architecture Review Report
|
||||
Date: [date]
|
||||
Engine: [name + version]
|
||||
GDDs Reviewed: [N]
|
||||
ADRs Reviewed: [M]
|
||||
|
||||
---
|
||||
|
||||
### Traceability Summary
|
||||
Total requirements: [N]
|
||||
✅ Covered: [X]
|
||||
⚠️ Partial: [Y]
|
||||
❌ Gaps: [Z]
|
||||
|
||||
### Coverage Gaps (no ADR exists)
|
||||
For each gap:
|
||||
❌ TR-[id]: [GDD] → [system] → [requirement]
|
||||
Suggested ADR: "/architecture-decision [suggested title]"
|
||||
Domain: [Physics/Rendering/etc]
|
||||
Engine Risk: [LOW/MEDIUM/HIGH]
|
||||
|
||||
### Cross-ADR Conflicts
|
||||
[List all conflicts from Phase 4]
|
||||
|
||||
### ADR Dependency Order
|
||||
[Topologically sorted implementation order from Phase 4 — dependency ordering section]
|
||||
[Unresolved dependencies and cycles if any]
|
||||
|
||||
### GDD Revision Flags
|
||||
[GDD assumptions that conflict with verified engine behaviour — from Phase 5b]
|
||||
[Or: "None — all GDD assumptions consistent with verified engine behaviour"]
|
||||
|
||||
### Engine Compatibility Issues
|
||||
[List all engine issues from Phase 5]
|
||||
|
||||
### Architecture Document Coverage
|
||||
[List missing systems and orphaned architecture from Phase 6]
|
||||
|
||||
---
|
||||
|
||||
### Verdict: [PASS / CONCERNS / FAIL]
|
||||
|
||||
PASS: All requirements covered, no conflicts, engine consistent
|
||||
CONCERNS: Some gaps or partial coverage, but no blocking conflicts
|
||||
FAIL: Critical gaps (Foundation/Core layer requirements uncovered),
|
||||
or blocking cross-ADR conflicts detected
|
||||
|
||||
### Blocking Issues (must resolve before PASS)
|
||||
[List items that must be resolved — FAIL verdict only]
|
||||
|
||||
### Required ADRs
|
||||
[Prioritised list of ADRs to create, most foundational first]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 8: Write and Update Traceability Index
|
||||
|
||||
Use `AskUserQuestion` for the write approval:
|
||||
- "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 Output (rtm mode only)
|
||||
|
||||
For `rtm` mode, use `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
|
||||
|
||||
RTM file format:
|
||||
|
||||
```markdown
|
||||
# Requirements Traceability Matrix (RTM)
|
||||
|
||||
> Last Updated: [date]
|
||||
> Mode: /architecture-review rtm
|
||||
> Coverage: [N]% full chain complete (GDD → ADR → Story → Test)
|
||||
|
||||
## How to read this matrix
|
||||
|
||||
| Column | Meaning |
|
||||
|--------|---------|
|
||||
| TR-ID | Stable requirement ID from tr-registry.yaml |
|
||||
| GDD | Source design document |
|
||||
| ADR | Architectural decision governing implementation |
|
||||
| Story | Story file that implements this requirement |
|
||||
| Test File | Automated test file path |
|
||||
| Test Status | COVERED / MISSING / NONE / NO STORY |
|
||||
|
||||
## Full Traceability Matrix
|
||||
|
||||
| TR-ID | GDD | Requirement | ADR | Story | Test File | Status |
|
||||
|-------|-----|-------------|-----|-------|-----------|--------|
|
||||
[Full matrix rows from Phase 3b]
|
||||
|
||||
## Coverage Summary
|
||||
|
||||
| Status | Count | % |
|
||||
|--------|-------|---|
|
||||
| COVERED — full chain complete | [N] | [%] |
|
||||
| MISSING test — story exists, no test | [N] | [%] |
|
||||
| NO STORY — ADR exists, not yet implemented | [N] | [%] |
|
||||
| NO ADR — architectural gap | [N] | [%] |
|
||||
| **Total requirements** | **[N]** | **100%** |
|
||||
|
||||
## Uncovered Requirements (Priority Fix List)
|
||||
|
||||
Requirements where the full chain is broken, prioritised by layer:
|
||||
|
||||
### Foundation layer gaps
|
||||
[list with suggested action per gap]
|
||||
|
||||
### Core layer gaps
|
||||
[list]
|
||||
|
||||
### Feature / Presentation layer gaps
|
||||
[list — lower priority]
|
||||
|
||||
## History
|
||||
|
||||
| Date | Full Chain % | Notes |
|
||||
|------|-------------|-------|
|
||||
| [date] | [%] | Initial RTM |
|
||||
```
|
||||
|
||||
### TR Registry Update
|
||||
|
||||
Also ask: "May I update `docs/architecture/tr-registry.yaml` with new requirement
|
||||
IDs from this review?"
|
||||
|
||||
If yes:
|
||||
- **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
|
||||
|
||||
This ensures all future story files can reference stable TR-IDs that persist
|
||||
across every subsequent architecture review.
|
||||
|
||||
### Reflexion Log Update
|
||||
|
||||
After writing the review report, append any 🔴 CONFLICT entries found in Phase 4
|
||||
to `docs/consistency-failures.md` (if the file exists):
|
||||
|
||||
```markdown
|
||||
### [YYYY-MM-DD] — /architecture-review — 🔴 CONFLICT
|
||||
**Domain**: Architecture / [specific domain e.g. State Ownership, Performance]
|
||||
**Documents involved**: [ADR-NNNN] vs [ADR-MMMM]
|
||||
**What happened**: [specific conflict — what each ADR claims]
|
||||
**Resolution**: [how it was or should be resolved]
|
||||
**Pattern**: [generalised lesson for future ADR authors in this domain]
|
||||
```
|
||||
|
||||
Only append CONFLICT entries — do not log GAP entries (missing ADRs are expected
|
||||
before the architecture is complete). Do not create the file if missing — only
|
||||
append when it already exists.
|
||||
|
||||
### Session State Update
|
||||
|
||||
After writing all approved files, silently append to
|
||||
`production/session-state/active.md`:
|
||||
|
||||
## Session Extract — /architecture-review [date]
|
||||
- Verdict: [PASS / CONCERNS / FAIL]
|
||||
- Requirements: [N] total — [X] covered, [Y] partial, [Z] gaps
|
||||
- New TR-IDs registered: [N, or "None"]
|
||||
- GDD revision flags: [comma-separated GDD names, or "None"]
|
||||
- Top ADR gaps: [top 3 gap titles from the report, or "None"]
|
||||
- Report: docs/architecture/architecture-review-[date].md
|
||||
|
||||
If `active.md` does not exist, create it with this block as the initial content.
|
||||
Confirm in conversation: "Session state updated."
|
||||
|
||||
The traceability index format:
|
||||
|
||||
```markdown
|
||||
# Architecture Traceability Index
|
||||
Last Updated: [date]
|
||||
Engine: [name + version]
|
||||
|
||||
## Coverage Summary
|
||||
- Total requirements: [N]
|
||||
- Covered: [X] ([%])
|
||||
- Partial: [Y]
|
||||
- Gaps: [Z]
|
||||
|
||||
## Full Matrix
|
||||
[Complete traceability matrix from Phase 3]
|
||||
|
||||
## Known Gaps
|
||||
[All ❌ items with suggested ADRs]
|
||||
|
||||
## Superseded Requirements
|
||||
[Requirements whose GDD was changed after the ADR was written]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 9: Handoff
|
||||
|
||||
After completing the review and writing approved files, present:
|
||||
|
||||
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"
|
||||
|
||||
Then close with `AskUserQuestion` tailored to the pre-gate checklist state:
|
||||
- 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
|
||||
|
||||
---
|
||||
|
||||
## Error Recovery Protocol
|
||||
|
||||
If any spawned agent returns BLOCKED, errors, or fails to complete:
|
||||
|
||||
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
|
||||
|
||||
---
|
||||
|
||||
## Collaborative Protocol
|
||||
|
||||
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
|
||||
Reference in New Issue
Block a user