pixelheros/CCGS Skill Testing Framework/skills/review/architecture-review.md

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.