193 lines
7.4 KiB
Markdown
193 lines
7.4 KiB
Markdown
# 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.
|