# Skill Test Spec: /architecture-review ## Skill Summary `/architecture-review` is an Opus-tier skill that validates a technical architecture document against the project's 8 required architecture sections and checks that it is internally consistent, non-contradictory with existing ADRs, and correctly targeting the pinned engine version. It produces a verdict of APPROVED / NEEDS REVISION / MAJOR REVISION NEEDED. In `full` review mode, the skill spawns two director gate agents in parallel: TD-ARCHITECTURE (technical-director) and LP-FEASIBILITY (lead-programmer). In `lean` or `solo` mode, both gates are skipped and noted. The skill is read-only — no files are written. --- ## Static Assertions (Structural) Verified automatically by `/skill-test static` — no fixture needed. - [ ] Has required frontmatter fields: `name`, `description`, `argument-hint`, `user-invocable`, `allowed-tools` - [ ] Has ≥2 phase headings - [ ] Contains verdict keywords: APPROVED, NEEDS REVISION, MAJOR REVISION NEEDED - [ ] Does NOT require "May I write" language (read-only skill) - [ ] Has a next-step handoff at the end - [ ] Documents gate behavior: TD-ARCHITECTURE + LP-FEASIBILITY in full mode; skipped in lean/solo --- ## Director Gate Checks In `full` mode: TD-ARCHITECTURE (technical-director) and LP-FEASIBILITY (lead-programmer) are spawned in parallel after the skill reads the architecture doc. In `lean` mode: both gates are skipped. Output notes: "TD-ARCHITECTURE skipped — lean mode" and "LP-FEASIBILITY skipped — lean mode". In `solo` mode: both gates are skipped with equivalent notes. --- ## Test Cases ### Case 1: Happy Path — Complete architecture doc in full mode **Fixture:** - `docs/architecture/architecture.md` exists with all 8 required sections populated - All sections reference the correct engine version from `docs/engine-reference/` - No contradictions with existing Accepted ADRs in `docs/architecture/` - `production/session-state/review-mode.txt` contains `full` **Input:** `/architecture-review docs/architecture/architecture.md` **Expected behavior:** 1. Skill reads the architecture document 2. Skill reads existing ADRs for cross-reference 3. Skill reads engine version reference 4. TD-ARCHITECTURE and LP-FEASIBILITY gate agents spawn in parallel 5. Both gates return APPROVED 6. Skill outputs section-by-section completeness check (8/8 sections present) 7. Verdict: APPROVED **Assertions:** - [ ] All 8 required sections are checked and reported - [ ] TD-ARCHITECTURE and LP-FEASIBILITY spawn in parallel (not sequentially) - [ ] Verdict is APPROVED when all sections are present and no conflicts exist - [ ] Skill does NOT write any files - [ ] Next-step handoff to `/create-control-manifest` or `/create-epics` is present --- ### Case 2: Failure Path — Missing required sections **Fixture:** - `docs/architecture/architecture.md` exists but is missing at least 2 required sections (e.g., no data model section, no error handling section) - `production/session-state/review-mode.txt` contains `full` **Input:** `/architecture-review docs/architecture/architecture.md` **Expected behavior:** 1. Skill reads the document and identifies missing sections 2. Section completeness shows fewer than 8/8 sections present 3. Missing sections are listed by name with specific remediation guidance 4. Verdict: MAJOR REVISION NEEDED (≥2 missing sections) **Assertions:** - [ ] Verdict is MAJOR REVISION NEEDED (not APPROVED or NEEDS REVISION) for ≥2 missing sections - [ ] Each missing section is named explicitly in the output - [ ] Remediation guidance is specific (what to add, not just "add missing sections") - [ ] Skill does NOT pass a document missing required sections --- ### Case 3: Partial Path — Architecture contradicts an existing ADR **Fixture:** - `docs/architecture/architecture.md` exists with all 8 sections present - One Accepted ADR in `docs/architecture/` establishes a constraint that the architecture doc contradicts (e.g., ADR-001 mandates ECS pattern; architecture.md describes a different pattern for the same system) **Input:** `/architecture-review docs/architecture/architecture.md` **Expected behavior:** 1. Skill reads the architecture doc and all existing ADRs 2. Conflict is detected between the architecture doc and the named ADR 3. Conflict entry names: the ADR number/title, the contradicting sections, and impact 4. Verdict: NEEDS REVISION (conflict exists but structure is otherwise sound) **Assertions:** - [ ] Verdict is NEEDS REVISION (not MAJOR REVISION NEEDED for a single contradiction) - [ ] The specific ADR number and title are named in the conflict entry - [ ] The contradicting sections in both documents are identified - [ ] Skill does NOT auto-resolve the contradiction --- ### Case 4: Edge Case — File not found **Fixture:** - The path provided does not exist in the project **Input:** `/architecture-review docs/architecture/nonexistent.md` **Expected behavior:** 1. Skill attempts to read the file 2. File not found 3. Skill outputs a clear error naming the missing file 4. Skill suggests checking `docs/architecture/` or running `/create-architecture` 5. Skill does NOT produce a verdict **Assertions:** - [ ] Skill outputs a clear error when the file is not found - [ ] No verdict is produced (APPROVED / NEEDS REVISION / MAJOR REVISION NEEDED) - [ ] Skill suggests a corrective action - [ ] Skill does NOT crash or produce a partial report --- ### Case 5: Director Gate — Full mode spawns both gates; solo mode skips both **Fixture (full mode):** - `docs/architecture/architecture.md` exists with all 8 sections - `production/session-state/review-mode.txt` contains `full` **Full mode expected behavior:** 1. TD-ARCHITECTURE gate spawns 2. LP-FEASIBILITY gate spawns in parallel with TD-ARCHITECTURE 3. Both gates complete before verdict is issued **Assertions (full mode):** - [ ] TD-ARCHITECTURE and LP-FEASIBILITY both appear in the output as completed gates - [ ] Both gates spawn in parallel (not one after the other) - [ ] Verdict reflects gate feedback **Fixture (solo mode):** - Same architecture doc - `production/session-state/review-mode.txt` contains `solo` **Solo mode expected behavior:** 1. Skill reads the architecture doc 2. Gates are NOT spawned 3. Output notes: "TD-ARCHITECTURE skipped — solo mode" and "LP-FEASIBILITY skipped — solo mode" 4. Verdict is based on structural checks only **Assertions (solo mode):** - [ ] Neither TD-ARCHITECTURE nor LP-FEASIBILITY appears as an active gate - [ ] Both skipped gates are noted in the output - [ ] Verdict is still produced based on the structural check alone --- ## Protocol Compliance - [ ] Does NOT write any files (read-only skill) - [ ] Presents section completeness check before issuing verdict - [ ] TD-ARCHITECTURE and LP-FEASIBILITY spawn in parallel in full mode - [ ] Skipped gates are noted by name and mode in lean/solo output - [ ] Verdict is one of exactly: APPROVED, NEEDS REVISION, MAJOR REVISION NEEDED - [ ] Ends with next-step handoff appropriate to verdict --- ## Coverage Notes - The 8 required architecture sections are project-specific; tests use the section list defined in the skill body — not re-enumerated here. - Engine version compatibility checking (cross-referencing `docs/engine-reference/`) is part of Case 1's happy path but not independently fixture-tested. - RTM (requirement traceability matrix) mode is a separate concern covered by the `/architecture-review` skill's own `rtm` argument mode, not tested here.