177 lines
6.1 KiB
Markdown
177 lines
6.1 KiB
Markdown
# Skill Test Spec: /ux-review
|
|
|
|
## Skill Summary
|
|
|
|
`/ux-review` validates an existing UX spec or HUD design document against
|
|
accessibility and interaction standards. It checks for required sections
|
|
(User Flows, Interaction States, Wireframe Description, Accessibility Notes),
|
|
completeness of interaction state definitions (hover, focus, disabled, error),
|
|
accessibility compliance (keyboard navigation, color contrast notes, screen
|
|
reader considerations), and consistency with the art bible or design system
|
|
if those documents exist.
|
|
|
|
The skill is read-only — it produces no file writes. Verdicts: APPROVED
|
|
(all checks pass), NEEDS REVISION (fixable issues found), or MAJOR REVISION
|
|
NEEDED (structural or accessibility failures). No director gates apply —
|
|
`/ux-review` IS the review gate for UX specs.
|
|
|
|
---
|
|
|
|
## 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 contain "May I write" language (skill is read-only)
|
|
- [ ] Has a next-step handoff (e.g., back to `/ux-design` for revision, or proceed to implementation)
|
|
|
|
---
|
|
|
|
## Director Gate Checks
|
|
|
|
None. `/ux-review` is itself the review gate for UX specs. No additional director
|
|
gates are invoked within this skill.
|
|
|
|
---
|
|
|
|
## Test Cases
|
|
|
|
### Case 1: Happy Path — Complete UX spec with all required sections, APPROVED
|
|
|
|
**Fixture:**
|
|
- `design/ux/hud.md` exists with all required sections populated:
|
|
- User Flows: complete player flow diagrams
|
|
- Interaction States: normal, hover, focus, disabled, error all defined
|
|
- Wireframe Description: layout described
|
|
- Accessibility Notes: keyboard nav, contrast ratios, screen reader notes
|
|
|
|
**Input:** `/ux-review hud`
|
|
|
|
**Expected behavior:**
|
|
1. Skill reads `design/ux/hud.md`
|
|
2. Skill checks all 4 required sections — all present and non-empty
|
|
3. Skill checks interaction states — all 5 states defined
|
|
4. Skill checks accessibility notes — keyboard, contrast, and screen reader covered
|
|
5. Skill outputs: checklist of all passed checks
|
|
6. Verdict is APPROVED
|
|
|
|
**Assertions:**
|
|
- [ ] All 4 required sections are checked
|
|
- [ ] All 5 interaction states are verified present
|
|
- [ ] Verdict is APPROVED
|
|
- [ ] No files are written
|
|
|
|
---
|
|
|
|
### Case 2: Missing Accessibility Section — NEEDS REVISION
|
|
|
|
**Fixture:**
|
|
- `design/ux/hud.md` exists but the Accessibility Notes section is empty
|
|
- All other sections are fully populated
|
|
|
|
**Input:** `/ux-review hud`
|
|
|
|
**Expected behavior:**
|
|
1. Skill reads the file and checks all sections
|
|
2. Accessibility Notes section is empty — check fails
|
|
3. Skill outputs: "NEEDS REVISION — Accessibility Notes section is empty"
|
|
4. Skill lists specific items to add: keyboard navigation, color contrast ratios,
|
|
screen reader labels
|
|
5. Verdict is NEEDS REVISION
|
|
6. Handoff suggests returning to `/ux-design hud` to fill in the section
|
|
|
|
**Assertions:**
|
|
- [ ] NEEDS REVISION verdict is returned (not APPROVED or MAJOR REVISION NEEDED)
|
|
- [ ] Specific missing content items are listed
|
|
- [ ] Handoff points back to `/ux-design hud` for revision
|
|
- [ ] No files are written
|
|
|
|
---
|
|
|
|
### Case 3: Interaction States Incomplete — NEEDS REVISION
|
|
|
|
**Fixture:**
|
|
- `design/ux/settings-menu.md` exists
|
|
- Interaction States section only defines: normal and hover
|
|
- Missing: focus, disabled, error states
|
|
|
|
**Input:** `/ux-review settings-menu`
|
|
|
|
**Expected behavior:**
|
|
1. Skill reads the file and checks interaction states
|
|
2. Only 2 of 5 required states are defined
|
|
3. Skill reports: "NEEDS REVISION — Interaction states incomplete: missing focus, disabled, error"
|
|
4. Verdict is NEEDS REVISION with specific missing states named
|
|
|
|
**Assertions:**
|
|
- [ ] NEEDS REVISION verdict returned
|
|
- [ ] All 3 missing states are named explicitly in the output
|
|
- [ ] Skill does not return MAJOR REVISION NEEDED for a fixable gap
|
|
- [ ] Handoff suggests returning to `/ux-design settings-menu`
|
|
|
|
---
|
|
|
|
### Case 4: File Not Found — Error with remediation
|
|
|
|
**Fixture:**
|
|
- `design/ux/inventory-screen.md` does not exist
|
|
|
|
**Input:** `/ux-review inventory-screen`
|
|
|
|
**Expected behavior:**
|
|
1. Skill attempts to read `design/ux/inventory-screen.md` — file not found
|
|
2. Skill outputs: "UX spec not found: design/ux/inventory-screen.md"
|
|
3. Skill suggests running `/ux-design inventory-screen` to create the spec first
|
|
4. No review is performed; no verdict is issued
|
|
|
|
**Assertions:**
|
|
- [ ] Error message names the missing file with full path
|
|
- [ ] `/ux-design inventory-screen` is suggested as the remediation
|
|
- [ ] No review checklist is produced
|
|
- [ ] No verdict is issued (error state, not APPROVED/NEEDS REVISION)
|
|
|
|
---
|
|
|
|
### Case 5: Director Gate Check — No gate; ux-review is itself the review
|
|
|
|
**Fixture:**
|
|
- Valid UX spec file
|
|
|
|
**Input:** `/ux-review hud`
|
|
|
|
**Expected behavior:**
|
|
1. Skill performs the review and issues a verdict
|
|
2. No additional director agents are spawned
|
|
3. No gate IDs appear in output
|
|
|
|
**Assertions:**
|
|
- [ ] No director gate is invoked
|
|
- [ ] No gate skip messages appear
|
|
- [ ] Verdict is APPROVED, NEEDS REVISION, or MAJOR REVISION NEEDED — no gate verdict
|
|
|
|
---
|
|
|
|
## Protocol Compliance
|
|
|
|
- [ ] Checks all 4 required sections (User Flows, Interaction States, Wireframe,
|
|
Accessibility Notes)
|
|
- [ ] Checks all 5 interaction states (normal, hover, focus, disabled, error)
|
|
- [ ] Checks accessibility coverage (keyboard nav, contrast, screen reader)
|
|
- [ ] Does not write any files
|
|
- [ ] Issues specific, actionable feedback when verdict is not APPROVED
|
|
- [ ] Ends with next-step handoff to `/ux-design` for revision or implementation
|
|
|
|
---
|
|
|
|
## Coverage Notes
|
|
|
|
- MAJOR REVISION NEEDED is triggered when structural sections are entirely
|
|
absent (not just empty) or when fundamental interaction flows are missing
|
|
entirely; not tested with a separate fixture here.
|
|
- Art bible / design system consistency check (color palette alignment) is
|
|
mentioned as a capability but not separately fixture-tested.
|
|
- The case where an existing spec was written for a now-renamed screen is
|
|
not tested; the skill would review the file by path regardless of the name.
|