Elgato_dark/Claude-Code-Game-Studios
1
0
Fork 0
mirror of https://github.com/Donchitos/Claude-Code-Game-Studios synced 2026-04-21 13:27:18 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Release v0.4.0: UX pipeline, game-dev improvements

Browse source 
## New Skills (9)
- /quick-design: lightweight spec path for small changes (bypasses full GDD pipeline)
- /story-readiness: validates stories are implementation-ready before pickup
- /story-done: end-of-story completion review (criteria verification, deviation check, status update)
- /sprint-status: fast 30-line sprint snapshot, read-only
- /ux-design: guided section-by-section UX spec authoring (screen/flow/HUD/patterns)
- /ux-review: UX spec validation with APPROVED/NEEDS REVISION/MAJOR REVISION verdict
- /architecture-review, /create-architecture, /create-control-manifest,
  /create-epics-stories, /propagate-design-change, /review-all-gdds (pipeline completion)

## New Templates (7)
- player-journey.md: 6-phase emotional arc, critical moments, retention hooks
- difficulty-curve.md: difficulty axes, onboarding ramp, cross-system interactions
- ux-spec.md: per-screen UX spec with states, interaction map, data requirements, events
- hud-design.md: whole-game HUD with philosophy, info architecture, element specs
- accessibility-requirements.md: project-wide accessibility tier commitment and audit
- interaction-pattern-library.md: 26 standard + game-specific patterns with full state specs
- architecture-traceability.md: GDD requirements to ADR coverage matrix

## Updated Skills & Templates
- gate-check: Vertical Slice hard gate, playtesting strengthened, UX artifacts required
- team-ui: full UX pipeline integration (/ux-design + /ux-review + accessibility-specialist)
- game-design-document: Game Feel section (input latency, animation frames, impact moments)
- implementation-agent-protocol: /story-done as explicit final step of every story
- architecture-decision, design-system: pipeline completion updates

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Donchitos 2026-03-10 16:15:34 +11:00
parent 392e3befec
commit b1cad29b68
27 changed files with 7568 additions and 48 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

331
.claude/docs/templates/accessibility-requirements.md vendored Normal file
View file

@ -0,0 +1,331 @@
# Accessibility Requirements: [Game Title]
> **Status**: Draft | Committed | Audited | Certified
> **Author**: [ux-designer / producer]
> **Last Updated**: [Date]
> **Accessibility Tier Target**: [Basic / Standard / Comprehensive / Exemplary]
> **Platform(s)**: [PC / Xbox / PlayStation 5 / Nintendo Switch / iOS / Android]
> **External Standards Targeted**:
> - WCAG 2.1 Level [A / AA / AAA]
> - AbleGamers CVAA Guidelines
> - Xbox Accessibility Guidelines (XAG) [Yes / No / Partial]
> - PlayStation Accessibility (Sony Guidelines) [Yes / No / Partial]
> - Apple / Google Accessibility Guidelines [Yes / No / N/A — mobile only]
> **Accessibility Consultant**: [Name and organization, or "None engaged"]
> **Linked Documents**: `design/gdd/systems-index.md`, `docs/ux/interaction-pattern-library.md`
> **Why this document exists**: Per-screen accessibility annotations belong in
> UX specs. This document captures the project-wide accessibility commitments,
> the feature matrix across all systems, the test plan, and the audit history.
> It is created once during Technical Setup by the UX designer and producer,
> then updated as features are added and audits are completed. If a feature
> conflicts with a commitment made here, this document wins — change the feature,
> not the commitment, unless the producer approves a formal revision.
>
> **When to update**: After each `/gate-check` pass, after any accessibility
> audit, and whenever a new game system is added to `systems-index.md`.
---
## Accessibility Tier Definition
> **Why define tiers**: Accessibility is not binary. Defining four tiers gives
> the team a shared vocabulary, forces an explicit commitment at the start of
> production, and prevents scope creep in both directions ("we'll add it later"
> and "we have to support everything"). The tiers below are this project's
> definitions — the industry uses similar but not identical language. Commit to
> a tier with specific feature targets, not just the tier name.
### Tier Definitions
| Tier | Core Commitment | Typical Effort |
|------|----------------|----------------|
| **Basic** | Critical player-facing text is readable at standard resolution. No feature requires color discrimination alone. Volume controls exist for music, SFX, and voice independently. The game is completable without photosensitivity risk. | Low — primarily design constraints |
| **Standard** | All of Basic, plus: full input remapping on all platforms, subtitle support with speaker identification, adjustable text size, at least one colorblind mode, and no timed input that cannot be extended or toggled. | Medium — requires dedicated implementation work |
| **Comprehensive** | All of Standard, plus: screen reader support for menus, mono audio option, difficulty assist modes, HUD element repositioning, reduced motion mode, and visual indicators for all gameplay-critical audio. | High — requires platform API integration and significant UI architecture |
| **Exemplary** | All of Comprehensive, plus: full subtitle customization (font, size, color, background, position), high contrast mode, cognitive load assist tools, tactile/haptic alternatives for all audio-only cues, and external third-party accessibility audit. | Very High — requires dedicated accessibility budget and specialist consultation |
### This Project's Commitment
**Target Tier**: [Standard]
**Rationale**: [Write 3-5 sentences justifying the tier choice. Do not simply
state the tier — explain the reasoning. Consider: What is the game's genre and
how does it map to common accessibility barriers (e.g., fast-twitch games have
motor barriers; reading-heavy games have visual barriers)? Who is the target
player and what does the research say about disability prevalence in that group?
What are the platform requirements (Xbox requires XAG compliance for ID@Xbox)?
What is the team's capacity? What would dropping one tier cost the player base,
in concrete terms?
Example: "This is a narrative RPG with turn-based combat targeted at players
25-45. The turn-based structure eliminates the most severe motor barriers common
in action games, but the reading-heavy design creates significant visual and
cognitive barriers. Standard tier addresses all of these. Exemplary tier is not
achievable without a dedicated accessibility engineer. Xbox ID@Xbox program
requires XAG compliance for Game Pass consideration, which Standard meets.
Dropping to Basic would exclude players who rely on colorblind modes or input
remapping, estimated at 8-12% of the target audience based on AbleGamers data."]
**Features explicitly in scope (beyond tier baseline)**:
- [e.g., "Full subtitle customization — elevated from Comprehensive because our
game is dialogue-heavy and subtitles are a primary channel"]
- [e.g., "One-hand mode for controller — we have hold inputs critical to combat"]
**Features explicitly out of scope**:
- [e.g., "Screen reader for in-game world (not menus) — requires engine work
beyond current capacity. Documented in Known Intentional Limitations."]
---
## Visual Accessibility
> **Why this section comes first**: Visual impairments affect the largest
> proportion of players who use accessibility features. Color vision deficiency
> alone affects approximately 8% of men and 0.5% of women. Text legibility at
> TV viewing distance is frequently the single largest accessibility failure
> in shipped games. Document every visual feature before implementation begins,
> because retrofitting minimum text sizes or color decisions after assets are
> locked is expensive.
| Feature | Target Tier | Scope | Status | Implementation Notes |
|---------|-------------|-------|--------|---------------------|
| Minimum text size — menu UI | Standard | All menu screens | Not Started | 24px minimum at 1080p. At 4K, scale proportionally. Reference: WCAG 2.1 SC 1.4.4 requires text resizable to 200% without loss of content. |
| Minimum text size — subtitles | Standard | All voiced/captioned content | Not Started | 32px minimum at 1080p. Players viewing on TV at 3m are the constraint. |
| Minimum text size — HUD | Standard | In-game HUD | Not Started | 20px minimum for critical information (health, ammo, objective). Non-critical HUD elements may be smaller. |
| Text contrast — UI text on backgrounds | Standard | All UI text | Not Started | Minimum 4.5:1 ratio for body text (WCAG AA). 3:1 for large text (18px+ or 14px bold). Test with automated contrast checker on final color values. |
| Text contrast — subtitles | Standard | Subtitle display | Not Started | Minimum 7:1 ratio (WCAG AAA) for subtitles — players read them quickly and cannot control background. Use drop shadow or opaque background box by default. |
| Colorblind mode — Protanopia | Standard | All color-coded gameplay | Not Started | Red-green — affects ~6% of men. Primary concern: health bars, enemy indicators, map markers. Shift red signals to orange/yellow; shift green signals to teal. |
| Colorblind mode — Deuteranopia | Standard | All color-coded gameplay | Not Started | Green-red — affects ~1% of men. Similar to Protanopia in practical impact. Often the same palette adjustment covers both. Verify with Coblis or Colour Blindness Simulator. |
| Colorblind mode — Tritanopia | Standard | All color-coded gameplay | Not Started | Blue-yellow — rarer (~0.001%). Shift blue UI elements to purple; shift yellow to orange. |
| Color-as-only-indicator audit | Basic | All UI and gameplay | Not Started | List every place color is the SOLE differentiator in the table below. Each must have a non-color backup (icon, shape, pattern, text label) before shipping. |
| UI scaling | Standard | All UI elements | Not Started | Range: 75% to 150%. Default: 100%. Scaling must not break layout — test all screens at min and max. HUD scaling should be independent from menu scaling. |
| High contrast mode | Comprehensive | Menus (minimum); HUD (preferred) | Not Started | Replace all semi-transparent backgrounds with fully opaque. Replace mid-tone UI colors with black/white/system-high-contrast colors. All interactive elements outlined. |
| Brightness/gamma controls | Basic | Global | Not Started | Exposed in graphics settings. Include a reference calibration image (a gradient or symbol barely visible at correct calibration). Range: -50% to +50% from default. |
| Screen flash / strobe warning | Basic | All cutscenes, VFX | Not Started | (1) Pre-launch warning screen with photosensitivity seizure notice. (2) Audit all flash-heavy VFX against Harding FPA standard (no more than 3 flashes per second above luminance threshold). (3) Optional: flash reduction mode that lowers flash amplitude by 80%. |
| Motion/animation reduction mode | Standard | All UI transitions, camera shake, VFX | Not Started | Reduce or eliminate: screen shake, camera bob, motion blur, parallax scrolling in menus, looping background animations. Cannot fully eliminate: player movement animation (would break readability). Toggle in accessibility settings. |
| Subtitles — on/off | Basic | All voiced content | Not Started | Default: OFF (industry standard — many players prefer immersion). Prominently offered at first launch. |
| Subtitles — speaker identification | Standard | All voiced content | Not Started | Speaker name displayed before dialogue line. Color-coded by speaker IF colors differ by more than hue alone (test for colorblind compatibility). |
| Subtitles — style customization | Comprehensive | Subtitle display | Not Started | Font size (4 sizes minimum), background opacity (0–100%), text color (white / yellow / custom), position (bottom / top / player-relative). |
| Subtitles — sound effect captions | Comprehensive | Gameplay-critical SFX | Not Started | See Auditory Accessibility section for which SFX qualify. Format: [SOUND DESCRIPTION] in brackets, distinct from dialogue. |
### Color-as-Only-Indicator Audit
> Fill in every gameplay or UI element where color is currently the sole
> differentiator. Resolve each before shipping. A resolved entry has a non-color
> backup that works in all three colorblind modes above.
| Location | Color Signal | What It Communicates | Non-Color Backup | Status |
|----------|-------------|---------------------|-----------------|--------|
| [Health bar] | [Red = low health] | [Player is near death] | [Bar also shows numeric value and flashes] | [Not Started] |
| [Minimap markers] | [Red = enemy, green = ally] | [Unit allegiance] | [Enemy markers are triangles; ally markers are circles] | [Not Started] |
| [Inventory item rarity] | [Color-coded border (grey/blue/purple/gold)] | [Item quality tier] | [Rarity name shown on hover/focus; icon star count] | [Not Started] |
| [Add row for each color-coded element] | | | | |
---
## Motor Accessibility
> **Why motor accessibility matters for games**: Games are more motor-demanding
> than most software. A web form requires precise clicks; a game may require
> rapid simultaneous button combinations held for specific durations. Motor
> impairments span a wide range — from tremor (affecting precision) to
> hemiplegia (one functional hand) to RSI (affecting hold duration). The AbleGamers
> Able Assistance program estimates 35 million gamers in the US have a disability
> affecting their ability to play. Many of the features below cost very little
> to implement if planned from the start, and are extremely expensive to add post-launch.
| Feature | Target Tier | Scope | Status | Implementation Notes |
|---------|-------------|-------|--------|---------------------|
| Full input remapping | Standard | All gameplay inputs, all platforms | Not Started | Every input bound by default must be rebindable. Remapping applies to keyboard, mouse, controller, and any supported peripheral independently. No two actions may be bound to the same input simultaneously (warn on conflict). Persist remapping to player profile. |
| Input method switching | Standard | PC | Not Started | Player must be able to switch between keyboard/mouse and gamepad at any moment without restarting. UI must update prompts dynamically (show correct button icons for active input method). |
| One-hand mode | [Tier] | [Identify which features require two simultaneous hands] | Not Started | Audit every multi-input action. For each: can it be executed with a single hand? If not, provide a toggle alternative or hold-to-toggle version. Specify here which features have a one-hand path and which do not. |
| Hold-to-press alternatives | Standard | All hold inputs | Not Started | Every "hold [button] to [action]" must offer a toggle alternative. Toggle mode: first press activates, second press deactivates. Example: "Hold to sprint" becomes optional "toggle sprint" mode. List all hold inputs in the game here. |
| Rapid input alternatives | Standard | Any button mashing / rapid input sequences | Not Started | Any input requiring more than 3 presses per second sustained must offer a single-press toggle alternative. Example: Hades' "Hold to dash repeatedly" solves this elegantly. |
| Input timing adjustments | Standard | QTEs, timed button presses, rhythm inputs | Not Started | Provide a timing window multiplier in accessibility settings. Minimum range: 0.5x to 3.0x. Default: 1.0x. At 3.0x, a 500ms window becomes 1500ms. Document every timed input in this game and test at all multiplier values. |
| Aim assist | Standard | All ranged combat / targeting | Not Started | Not just on/off — provide granularity: Assist Strength (0–100%), Assist Radius, Aim Magnetism (snap-to-target), and Aim Slowdown (near-target deceleration) as separate sliders. Default values should be tuned to feel helpful, not intrusive. |
| Auto-sprint / movement assists | Standard | Movement systems | Not Started | "Hold to sprint" toggle (covered above). Additionally: auto-run option (hold direction, player continues without input). Specify any movement input that is held continuously in normal gameplay. |
| Platforming / traversal assists | [Tier] | [If game has platforming] | Not Started | Evaluate whether auto-grab (generous ledge detection), coyote time extension, and jump height adjustment are appropriate for this game's design. If platforming is not a game system, mark N/A. |
| HUD element repositioning | Comprehensive | All HUD elements | Not Started | Allow players to move health bars, minimaps, and quest trackers to their preferred screen position. Particularly important for players using head-tracking or eye-gaze hardware who may have reduced peripheral vision coverage. |
---
## Cognitive Accessibility
> **Why cognitive accessibility is often under-specced**: Cognitive accessibility
> affects players with ADHD, dyslexia, autism spectrum conditions, acquired brain
> injuries, and anxiety disorders — a larger combined population than many studios
> realize. It also benefits all players in high-stress moments. The most common
> failures are: no pause anywhere, tutorial information that can only be seen once,
> and systems that require tracking too many simultaneous states. Games like
> Hades and Celeste have demonstrated that cognitive assist options (god mode,
> persistent reminders, extended text display) do not harm the experience for
> players who don't use them.
| Feature | Target Tier | Scope | Status | Implementation Notes |
|---------|-------------|-------|--------|---------------------|
| Difficulty options | Standard | All gameplay difficulty parameters | Not Started | Separate granular sliders where possible (damage dealt, damage received, enemy aggression, enemy speed) rather than a single Easy/Normal/Hard label. Document which parameters are adjustable and which are fixed. Fixed parameters require a design justification. |
| Pause anywhere | Basic | All gameplay states | Not Started | Players must be able to pause during any gameplay state, including cutscenes, dialogue, and tutorial sequences. Document any state where pausing is currently prevented and the design justification for that restriction. Any restriction is a risk. |
| Tutorial persistence | Standard | All tutorials and help text | Not Started | After dismissing a tutorial prompt, the player must be able to retrieve it from a Help section in the menu. Do not rely on players absorbing tutorials on first encounter — AbleGamers research shows many players dismiss prompts on reflex. |
| Quest / objective clarity | Standard | Quest and objective systems | Not Started | The current active objective must be accessible within 2 button presses at all times during gameplay. Display the full objective text on demand, not just a truncated marker. Avoid objectives that require inference ("investigate the northern region" — where exactly?). |
| Visual indicators for audio-only information | Standard | All SFX that carry gameplay information | Not Started | Audit every sound effect that communicates gameplay-critical state. For each: is there a visual equivalent? Directional audio (off-screen enemy) needs a screen-edge indicator. Critical warnings (boss phase transition, trap trigger) need visual cues. See Auditory Accessibility for full list. |
| Reading time for UI | Standard | All auto-dismissing dialogs | Not Started | No dialog, notification, or tooltip that contains actionable information may auto-dismiss in less than 5 seconds. Preferred: do not auto-dismiss at all — require player confirmation. Document every auto-dismissing element here and its current duration. |
| Cognitive load documentation | Comprehensive | Per game system | Not Started | For each system in systems-index.md, document the maximum number of things it asks the player to simultaneously track. Flag any system where the number exceeds 4. This is not a hard rule but a review trigger — high cognitive load systems need compensating UI clarity. See Per-Feature Accessibility Matrix below. |
| Navigation assists | Standard | World navigation | Not Started | Fast travel (to previously visited locations), waypoint system for current objective, optional objective indicator always visible. Document which of these apply to this game's design and which are intentionally omitted. |
---
## Auditory Accessibility
> **Why auditory accessibility matters even for players without hearing loss**:
> 7% of players are deaf or hard of hearing. Additionally, a large portion of
> players regularly play in environments where audio is reduced or absent (commute,
> shared household, infant sleeping). Any gameplay-critical information delivered
> only through audio is a design failure even before accessibility is considered.
> The guiding principle: every sound that changes what the player should DO next
> must have a visual equivalent.
| Feature | Target Tier | Scope | Status | Implementation Notes |
|---------|-------------|-------|--------|---------------------|
| Subtitles for all spoken dialogue | Basic | All voiced content | Not Started | 100% coverage — no exceptions. Include narration, in-engine dialogue, radio/environmental dialogue heard from a distance. Test subtitle sync against voice acting timing. |
| Closed captions for gameplay-critical SFX | Comprehensive | Identified SFX list (below) | Not Started | Not all SFX need captions — only those that communicate state the player cannot infer visually. See the SFX audit table below. |
| Mono audio option | Comprehensive | Global audio output | Not Started | Folds stereo/spatial audio to mono. Preserves volume balance between channels rather than summing to full volume on both sides. Essential for players with single-sided deafness. |
| Independent volume controls | Basic | Music / SFX / Voice / UI audio buses | Not Started | Four independent sliders minimum. Persist to player profile. Range: 0–100%, default 80%. Expose in both main settings and the pause menu. |
| Visual representations for directional audio | Comprehensive | All off-screen threats and audio events | Not Started | Screen-edge indicator pointing toward the audio source. Opacity scales with audio volume (closer = more opaque). Two variants: threat indicators (red) and information indicators (neutral). Example: The Last of Us Part II uses screen-edge indicators for off-screen enemy positions. |
| Hearing aid compatibility mode | Standard | High-frequency audio cues | Not Started | Audit all audio cues for frequency range. Any cue that communicates critical information only through high-frequency sound (above 4kHz) must have a low-frequency or visual equivalent. Hearing aids often filter high frequencies. |
### Gameplay-Critical SFX Audit
> Identify every sound effect that communicates state the player needs to act on.
> Each entry in this table requires either a confirmed visual backup or a caption.
| Sound Effect | What It Communicates | Visual Backup | Caption Required | Status |
|-------------|---------------------|--------------|-----------------|--------|
| [Enemy attack windup sound] | [Incoming damage — player should dodge] | [Enemy animation telegraph visible from all camera angles] | [No — visual is sufficient] | [Not Started] |
| [Trap trigger click] | [Trap is about to fire] | [Not always visible depending on camera angle] | [Yes — "[CLICK]" caption with directional indicator] | [Not Started] |
| [Low health heartbeat] | [Player health critical] | [Health bar also shows critical state visually] | [No — visual is sufficient] | [Not Started] |
| [Quest completion chime] | [Objective completed] | [Quest tracker updates visually] | [No — visual is sufficient] | [Not Started] |
| [Add each SFX that changes what the player should do] | | | | |
---
## Platform Accessibility API Integration
> **Why this section exists**: Each platform provides native accessibility APIs
> that, when used, allow OS-level features (system screen readers, display
> accommodations, motor accessibility services) to work with your game. Ignoring
> these APIs does not break the game, but it means players who rely on OS-level
> accessibility tools get no benefit from them inside your game. Xbox in particular
> requires XAG compliance for certification. Verify platform requirements before
> committing to a tier — platform requirements set a floor, not a ceiling.
| Platform | API / Standard | Features Planned | Status | Notes |
|----------|---------------|-----------------|--------|-------|
| Xbox (GDK) | Xbox Game Core Accessibility / XAG | [Input remapping via Xbox Ease of Access, high contrast support, narrator integration for menus] | Not Started | XAG compliance is required for ID@Xbox Game Pass consideration. Review XAG checklist at https://docs.microsoft.com/gaming/accessibility/guidelines |
| PlayStation 5 | Sony Accessibility Guidelines / AccessibilityNode API | [Screen reader passthrough for menus, mono audio, high contrast] | Not Started | PS5 natively supports system-level audio description and mono audio if the game exposes AccessibilityNode data on UI elements. |
| Steam (PC) | Steam Accessibility Features / SDL | [Controller input remapping via Steam Input, subtitle support] | Not Started | Steam Input allows system-level remapping independent of in-game remapping. In-game remapping still required for keyboard/mouse. |
| iOS | UIAccessibility / VoiceOver | [VoiceOver support for menus if mobile port planned] | N/A | Only required if mobile release is in scope. |
| Android | AccessibilityService / TalkBack | [TalkBack support for menus if mobile port planned] | N/A | Only required if mobile release is in scope. |
| PC (Screen Reader) | JAWS / NVDA / Windows Narrator | [Menu navigation announcements] | Not Started | Requires UI elements to expose accessible names and roles via platform UI layer. Godot 4.5+ AccessKit integration covers this for supported control types. Verify against engine-reference/godot/ docs. |
---
## Per-Feature Accessibility Matrix
> **Why this matrix exists**: Accessibility is not a list of settings — it is a
> property of every game system. This matrix creates the "accessibility impact"
> view of the game: which systems have which barriers, and whether those barriers
> are addressed. When a new system is added to systems-index.md, a row must be
> added here. If a system has an unaddressed accessibility concern, it cannot be
> marked Approved in the systems index.
| System | Visual Concerns | Motor Concerns | Cognitive Concerns | Auditory Concerns | Addressed | Notes |
|--------|----------------|---------------|-------------------|------------------|-----------|-------|
| [Combat System] | [Enemy health bars are color-coded; attack animations may cause motion sickness] | [Rapid input required for combos; hold inputs for guard] | [Track enemy patterns + cooldowns + player resources simultaneously] | [Audio cues for off-screen attacks; critical damage warning sounds] | [Partial] | [Colorblind palette applied; hold-to-block toggle needed] |
| [Inventory / Equipment] | [Item rarity conveyed by border color] | [No motor concerns — turn-based] | [Item stats comparison requires reading multiple values] | [None — no critical audio in this system] | [Partial] | [Non-color rarity indicators in progress] |
| [Dialogue System] | [Subtitle display depends on contrast settings] | [No motor concerns] | [Long dialogue trees with time pressure on dialogue choices] | [All dialogue must be subtitled] | [Not Started] | [Timed dialogue choices must support extended timer option] |
| [Navigation / World Map] | [Map marker colors] | [No motor concerns] | [Quest objective clarity; waypoint visibility] | [Audio pings for objectives have no visual equivalent] | [Not Started] | |
| [Add system from systems-index.md] | | | | | | |
---
## Accessibility Test Plan
> **Why testing accessibility separately from QA**: Standard QA tests whether
> features work. Accessibility testing tests whether features work for players
> who use them. These are different tests. A subtitle system can pass QA (it
> displays text) and fail accessibility testing (the text is unreadable at TV
> distance by a player with low vision). Plan for three test types: automated
> (contrast ratios, text sizes), manual internal (team members simulating
> impairments using accessibility simulators), and user testing (players who
> actually use these features).
| Feature | Test Method | Test Cases | Pass Criteria | Responsible | Status |
|---------|------------|------------|--------------|-------------|--------|
| Text contrast ratios | Automated — contrast analyzer tool on all UI screenshots | All text/background combinations at all game states | All body text ≥ 4.5:1; all large text ≥ 3:1; subtitle backgrounds ≥ 7:1 | ux-designer | Not Started |
| Colorblind modes | Manual — Coblis simulator on all game screenshots with modes enabled | Gameplay screenshots in exploration, combat, inventory in each mode | No essential information is lost in any mode; player can complete all objectives without color discrimination | ux-designer | Not Started |
| Input remapping | Manual — remap all inputs to non-default bindings, complete tutorial and first level | All default inputs rebound; gameplay functions correctly; no binding conflict possible | All actions accessible after remapping; conflict prevention works; bindings persist across restart | qa-tester | Not Started |
| Subtitle accuracy | Manual — verify against voice script, check all lines | All voiced content; subtitle timing; speaker identification | 100% of voiced lines subtitled; speaker identified for all multi-character scenes; no subtitle display for more than 3 seconds after line ends | qa-tester | Not Started |
| Hold input toggles | Manual — enable all toggle alternatives, complete all combat and traversal sequences | All hold inputs in toggle mode | All hold actions completable in toggle mode; no gameplay state requires sustained hold when toggle is enabled | qa-tester | Not Started |
| Reduced motion mode | Manual — enable mode, navigate all menus and complete first hour of gameplay | All menu transitions; all HUD animations; all camera shake events | No looping animations in menus; no camera shake above threshold; all screen transitions are cross-fade or cut | ux-designer | Not Started |
| Platform screen reader (menu) | Manual — enable OS screen reader, navigate all menus | Main menu, settings, pause menu, inventory, map | All interactive menu elements have screen reader announcements; navigation order is logical; no element unreachable by keyboard/D-pad | ux-designer | Not Started |
| User testing — colorblind | User testing with colorblind participants | Full game session with each colorblind mode | Participants complete all content without requesting color clarification; no session-stopping confusion | producer | Not Started |
| User testing — motor impairment | User testing with participants using one hand or adaptive controllers | Full game session with toggle and extended timing modes enabled | Participants complete all MVP content within tolerance of able-bodied completion time | producer | Not Started |
---
## Known Intentional Limitations
> **Why document what is NOT included**: Omissions left undocumented become
> surprises at certification or in community feedback. Documenting a limitation
> with a rationale demonstrates that it was a deliberate choice, not an oversight.
> It also identifies which players are not served and what the mitigation is.
> Every entry here is a risk — assess it honestly.
| Feature | Tier Required | Why Not Included | Risk / Impact | Mitigation |
|---------|--------------|-----------------|--------------|------------|
| [Screen reader support for in-game world (NPCs, objects, environmental text)] | Exemplary | Engine (Godot 4.6) AccessKit integration covers menus only; extending to the game world requires a custom spatial audio description system beyond current scope | Affects blind and low-vision players who can navigate menus but cannot independently explore the game world | Ensure all critical world information is duplicated in accessible menu systems (quest log, map); evaluate for post-launch DLC |
| [Full subtitle customization (font/color/background)] | Comprehensive | Scope reduction — targeting Standard tier. Custom font rendering in Godot requires additional asset pipeline work | Affects deaf and hard-of-hearing players with specific legibility needs; particularly affects players with dyslexia who use custom fonts | Provide two preset subtitle styles (default and high-readability) as a partial mitigation; log for post-launch update |
| [Tactile/haptic alternatives for all audio cues] | Exemplary | Platform rumble API integration for non-Xbox platforms is out of scope for v1.0 | Affects deaf players relying on haptic feedback; PC players with non-Xbox controllers get no haptic response | Xbox controller haptic integration is in scope; evaluate PlayStation DualSense haptic API for a post-launch patch |
| [Add any other intentionally excluded accessibility feature] | | | | |
---
## Audit History
> **Why track audit history**: Accessibility is not certified once and done.
> Platform requirements change. New features may introduce new barriers. Legal
> standards evolve. An audit history demonstrates due diligence and helps identify
> regressions between audits.
| Date | Auditor | Type | Scope | Findings Summary | Status |
|------|---------|------|-------|-----------------|--------|
| [Date] | [Internal — ux-designer] | Internal review | [Pre-submission checklist against committed tier] | [e.g., "12 items verified, 3 open issues: subtitle contrast below target in 2 scenes, color-only indicator on minimap not resolved"] | [In Progress] |
| [Date] | [External — AbleGamers Player Panel] | User testing | [Motor accessibility — one-hand mode and timing adjustments] | [e.g., "Toggle modes functional. Timed QTE window at 3x still failed for one participant — recommend 5x option."] | [Findings addressed] |
| [Add row for each audit] | | | | | |
---
## External Resources
| Resource | URL | Relevance |
|----------|-----|-----------|
| WCAG 2.1 (Web Content Accessibility Guidelines) | https://www.w3.org/TR/WCAG21/ | Foundational accessibility standard — contrast ratios, text sizing, input requirements |
| Game Accessibility Guidelines | https://gameaccessibilityguidelines.com | Comprehensive game-specific checklist organized by category and cost |
| AbleGamers Player Panel | https://ablegamers.org/player-panel/ | User testing service and consulting with disabled gamers |
| Xbox Accessibility Guidelines (XAG) | https://docs.microsoft.com/gaming/accessibility/guidelines | Required reading for Xbox certification; well-structured feature checklist |
| PlayStation Accessibility Guidelines | https://www.playstation.com/en-us/accessibility/ | Sony platform requirements; also contains well-written design guidance |
| Colour Blindness Simulator (Coblis) | https://www.color-blindness.com/coblis-color-blindness-simulator/ | Free tool for simulating colorblind modes on screenshots |
| Accessible Games Database | https://accessible.games | Research and examples of accessible game design decisions |
| CVAA (21st Century Communications and Video Accessibility Act) | https://www.fcc.gov/consumers/guides/21st-century-communications-and-video-accessibility-act-cvaa | US legal requirement for games with communication features (voice chat, messaging) |
---
## Open Questions
| Question | Owner | Deadline | Resolution |
|----------|-------|----------|-----------|
| [Does Godot 4.6 AccessKit support dynamic accessibility node updates for HUD elements, or only static menus?] | [ux-designer] | [Before Technical Setup gate] | [Unresolved — check engine-reference/godot/ docs] |
| [What is the Xbox ID@Xbox minimum XAG compliance requirement for our release window?] | [producer] | [Before Pre-Production gate] | [Unresolved] |
| [Will the dialogue system support timed choice extensions without a full architecture change?] | [lead-programmer] | [During Technical Design] | [Unresolved] |
| [Add question] | [Owner] | [Deadline] | [Resolution] |

42
.claude/docs/templates/architecture-decision-record.md vendored
View file

@ -12,6 +12,29 @@
[Who was involved in this decision]
## Engine Compatibility
| Field | Value |
|-------|-------|
| **Engine** | [e.g. Godot 4.6 / Unity 6 / Unreal Engine 5.4] |
| **Domain** | [Physics / Rendering / UI / Audio / Navigation / Animation / Networking / Core / Input / Scripting] |
| **Knowledge Risk** | [LOW — in training data / MEDIUM — near cutoff, verify / HIGH — post-cutoff, must verify] |
| **References Consulted** | [e.g. `docs/engine-reference/godot/modules/physics.md`, `breaking-changes.md`] |
| **Post-Cutoff APIs Used** | [Specific APIs from post-cutoff engine versions this decision depends on, or "None"] |
| **Verification Required** | [Concrete behaviours to test against the target engine version before shipping, or "None"] |
> **Note**: If Knowledge Risk is MEDIUM or HIGH, this ADR must be re-validated if the
> project upgrades engine versions. Flag it as "Superseded" and write a new ADR.
## ADR Dependencies
| Field | Value |
|-------|-------|
| **Depends On** | [ADR-NNNN (must be Accepted before this can be implemented), or "None"] |
| **Enables** | [ADR-NNNN (this ADR unlocks that decision), or "None"] |
| **Blocks** | [Epic/Story name — cannot start until this ADR is Accepted, or "None"] |
| **Ordering Note** | [Any sequencing constraint that isn't captured above] |
## Context
### Problem Statement
@ -120,8 +143,21 @@ creates. These become the contracts that implementers must respect.]
- [ ] [Measurable criterion 2]
- [ ] [Performance criterion]
## GDD Requirements Addressed
<!-- This section is MANDATORY. Every ADR must trace back to at least one GDD
requirement, or explicitly state it is a foundational decision with no GDD
dependency. Traceability is audited by /architecture-review. -->
| GDD Document | System | Requirement | How This ADR Satisfies It |
|-------------|--------|-------------|--------------------------|
| [e.g. `design/gdd/combat.md`] | [e.g. Combat] | [e.g. "Hitbox detection must resolve within 1 frame"] | [e.g. "Jolt physics collision queries run synchronously in _physics_process"] |
> If this is a foundational decision with no direct GDD dependency, write:
> "Foundational — no GDD requirement. Enables: [list what GDD systems this
> decision unlocks or constrains]"
## Related
- [Link to related ADRs]
- [Link to related design documents]
- [Link to relevant code files]
- [Link to related ADRs — note if supersedes, contradicts, or depends on]
- [Link to relevant code files once implemented]

101
.claude/docs/templates/architecture-traceability.md vendored Normal file
View file

@ -0,0 +1,101 @@
# Architecture Traceability Index
<!-- Living document — updated by /architecture-review after each review run.
Do not edit manually unless correcting an error. -->
## Document Status
- **Last Updated**: [YYYY-MM-DD]
- **Engine**: [e.g. Godot 4.6]
- **GDDs Indexed**: [N]
- **ADRs Indexed**: [M]
- **Last Review**: [link to docs/architecture/architecture-review-[date].md]
## Coverage Summary
| Status | Count | Percentage |
|--------|-------|-----------|
| ✅ Covered | [X] | [%] |
| ⚠️ Partial | [Y] | [%] |
| ❌ Gap | [Z] | [%] |
| **Total** | **[N]** | |
---
## Traceability Matrix
<!-- One row per technical requirement extracted from a GDD.
A "technical requirement" is any GDD statement that implies a specific
architectural decision: data structures, performance constraints, engine
capabilities needed, cross-system communication, state persistence. -->
| Req ID | GDD | System | Requirement Summary | ADR(s) | Status | Notes |
|--------|-----|--------|---------------------|--------|--------|-------|
| TR-[gdd]-001 | [filename] | [system name] | [one-line summary] | [ADR-NNNN] | ✅ | |
| TR-[gdd]-002 | [filename] | [system name] | [one-line summary] | — | ❌ GAP | Needs `/architecture-decision [title]` |
---
## Known Gaps
Requirements with no ADR coverage, prioritised by layer (Foundation first):
### Foundation Layer Gaps (BLOCKING — must resolve before coding)
- [ ] TR-[id]: [requirement] — GDD: [file] — Suggested ADR: "[title]"
### Core Layer Gaps (must resolve before relevant system is built)
- [ ] TR-[id]: [requirement] — GDD: [file] — Suggested ADR: "[title]"
### Feature Layer Gaps (should resolve before feature sprint)
- [ ] TR-[id]: [requirement] — GDD: [file] — Suggested ADR: "[title]"
### Presentation Layer Gaps (can defer to implementation)
- [ ] TR-[id]: [requirement] — GDD: [file] — Suggested ADR: "[title]"
---
## Cross-ADR Conflicts
<!-- Pairs of ADRs that make contradictory claims. Must be resolved. -->
| Conflict ID | ADR A | ADR B | Type | Status |
|-------------|-------|-------|------|--------|
| CONFLICT-001 | ADR-NNNN | ADR-MMMM | Data ownership | 🔴 Unresolved |
---
## ADR → GDD Coverage (Reverse Index)
<!-- For each ADR, which GDD requirements does it address? -->
| ADR | Title | GDD Requirements Addressed | Engine Risk |
|-----|-------|---------------------------|-------------|
| ADR-0001 | [title] | TR-combat-001, TR-combat-002 | HIGH |
---
## Superseded Requirements
<!-- Requirements that existed in a GDD when an ADR was written, but the GDD
has since changed. The ADR may need updating. -->
| Req ID | GDD | Change | Affected ADR | Status |
|--------|-----|--------|-------------|--------|
| TR-[id] | [file] | [what changed] | ADR-NNNN | 🔴 ADR needs update |
---
## How to Use This Document
**When writing a new ADR**: Add it to the "ADR → GDD Coverage" table and mark
the requirements it satisfies as ✅ in the matrix.
**When approving a GDD change**: Scan the matrix for requirements from that GDD
and check whether the change invalidates any existing ADR. Add to "Superseded
Requirements" if so.
**When running `/architecture-review`**: The skill will update this document
automatically with the current state.
**Gate check**: The Pre-Production gate requires this document to exist and to
have zero Foundation Layer Gaps.

16
.claude/docs/templates/collaborative-protocols/implementation-agent-protocol.md vendored
View file

@ -40,10 +40,11 @@ Before writing any code:
- For multi-file changes, list all affected files
- Wait for "yes" before using Write/Edit tools
6. **Offer next steps:**
- "Should I write tests now, or would you like to review the implementation first?"
- "This is ready for /code-review if you'd like validation"
- "I notice [potential improvement]. Should I refactor, or is this good for now?"
6. **Complete the story with `/story-done`:**
- When implementation (and tests, if written) is complete, invoke `/story-done [story-file-path]`
- This verifies acceptance criteria, checks for GDD/ADR deviations, prompts code review, and updates the story status
- Do NOT mark a story complete manually — always go through `/story-done`
- If no story file exists for this work (ad-hoc task), offer `/code-review` directly instead
#### Example Interaction Pattern
@ -109,7 +110,11 @@ User: "A, write tests"
You: [creates tests/combat/test_damage_calculator.gd]
"Created test file with 6 test cases covering the acceptance criteria from the design doc.
All tests passing. Ready to commit?"
All tests passing.
Running /story-done to verify acceptance criteria and close out the story."
[/story-done runs — verifies criteria, checks deviations, prompts code review, updates story status]
```
#### Collaborative Mindset
@ -120,6 +125,7 @@ You: [creates tests/combat/test_damage_calculator.gd]
- Flag deviations from design docs explicitly — designer should know if implementation differs
- Rules are your friend — when they flag issues, they're usually right
- Tests prove it works — offer to write them proactively
- Story completion is explicit — use `/story-done` to close every story, never assume done because code is written
#### Structured Decision UI

330
.claude/docs/templates/difficulty-curve.md vendored Normal file
View file

@ -0,0 +1,330 @@
# Difficulty Curve: [Game Title]
> **Status**: Draft | In Review | Approved
> **Author**: [game-designer / systems-designer]
> **Last Updated**: [Date]
> **Links To**: `design/gdd/game-concept.md`
> **Relevant GDDs**: [e.g., `design/gdd/combat.md`, `design/gdd/progression.md`]
---
## Difficulty Philosophy
[One paragraph establishing this game's relationship with difficulty. This is
not a mechanical description — it is a design value statement that all tuning
decisions must serve.
The four common difficulty philosophies are:
1. **Masochistic challenge as the core fantasy**: Difficulty is the product.
Overcoming it is the emotional reward. Reducing difficulty removes the
point. (Dark Souls, Celeste at max assist off)
2. **Accessible entry, optional depth**: The base experience is completable by
most players; depth and challenge are opt-in for those who want them.
(Hades, Hollow Knight with accessibility modes)
3. **Difficulty serves narrative pacing**: Challenge rises and falls to match
story beats. The player must feel capable during story resolution and
threatened during story crisis. (The Last of Us, God of War)
4. **Relaxed engagement**: Challenge is present but never the focus. Failure
is gentle and infrequent. The experience prioritizes comfort and expression
over obstacle. (Stardew Valley, Animal Crossing)
State the philosophy explicitly, then add one sentence on what the player is
permitted to feel: are they allowed to feel frustrated? For how long before the
design must intervene? What is the acceptable cost of failure?]
---
## Difficulty Axes
> **Guidance**: Most games have multiple independent dimensions of challenge.
> Identifying them explicitly prevents the mistake of tuning only one axis
> (usually execution difficulty) while leaving others unexamined. A game can
> feel "easy" on execution but overwhelming on decision complexity — players
> experience this as confusing, not engaging.
>
> For each axis, answer: can the player control or reduce this axis through
> choices, builds, or settings? If not, it is a forced challenge dimension —
> be very intentional about how it is used.
| Axis | Description | Primary Systems | Player Control? |
|------|-------------|----------------|-----------------|
| **Execution difficulty** | [The precision and timing demands of core actions. e.g., "Dodging enemy attacks requires correct timing within a 200ms window."] | [e.g., Combat, movement] | [Yes — practice reduces this / No — fixed mechanical threshold] |
| **Knowledge difficulty** | [The cost of not knowing information. e.g., "Enemy weaknesses are not telegraphed; players who have not discovered them take significantly more damage."] | [e.g., Enemy design, UI, lore] | [Yes — through in-game discovery / No — requires external knowledge] |
| **Resource pressure** | [How scarce are the resources needed to progress? e.g., "Health consumables are limited; efficient play is required to sustain long dungeon runs."] | [e.g., Economy, loot, crafting] | [Yes — through build optimization / Partially] |
| **Time pressure** | [Does the player have time to think, or does the game demand rapid decisions? e.g., "Enemy spawn timers and attack windows require real-time response."] | [e.g., Combat pacing, timers] | [Yes — through difficulty settings / No — core to genre] |
| **Decision complexity** | [How many meaningful choices must the player evaluate simultaneously? e.g., "Build decisions interact across 4 systems; suboptimal combinations create compounding disadvantage."] | [e.g., Progression, inventory, skills] | [Yes — through UI and tutorialization / No — inherent to strategy depth] |
| **[Add axis]** | [Description] | [Systems] | [Player control] |
---
## Difficulty Curve Overview
> **Guidance**: This table describes the intended challenge arc across the whole
> game. Difficulty levels use a 1-10 scale where 1 = no meaningful challenge,
> 10 = maximum challenge the game can produce. The scale is relative to THIS game's
> design intent — a 6/10 in a soulslike is not the same as a 6/10 in a cozy sim.
>
> "Primary challenge type" refers to the difficulty axis (from the table above)
> that is doing the most work in this phase. New systems introduced should list
> only systems introduced for the FIRST TIME — the cognitive load of learning
> a new system is itself a form of difficulty.
>
> "Target player state" is the emotional state the designer intends. If the actual
> playtested state diverges from the intended state, this column is what needs
> to be achieved.
| Phase | Duration | Difficulty Level (1-10) | Primary Challenge Type | New Systems Introduced | Target Player State |
|-------|----------|------------------------|----------------------|----------------------|---------------------|
| [Prologue / Tutorial] | [e.g., 0-15 min] | [2/10] | [Knowledge] | [Core movement, basic interaction] | [Safe, curious, building confidence] |
| [Early game] | [e.g., 15 min - 2 hrs] | [3-5/10] | [Execution] | [Combat, inventory, first upgrade path] | [Learning, occasional failure, clear cause-effect] |
| [Mid game - opening] | [e.g., 2-6 hrs] | [5-7/10] | [Decision complexity] | [Build choices, advanced enemies, crafting] | [Engaged, strategizing, feeling growth] |
| [Mid game - depth] | [e.g., 6-15 hrs] | [6-8/10] | [Resource pressure] | [Elite enemies, optional hard content, endgame previews] | [Challenged, invested, approaching mastery] |
| [Late game] | [e.g., 15-25 hrs] | [7-9/10] | [Execution + knowledge] | [Endgame systems, NG+ or equivalent] | [Mastery, confident in build identity, seeking peak challenge] |
| [Optional / Endgame] | [e.g., 25+ hrs] | [8-10/10] | [All axes combined] | [Mastery challenges, achievement targets] | [Expert play, self-imposed goals, community comparison] |
---
## Onboarding Ramp
> **Guidance**: The first hour deserves its own detailed breakdown because it
> does the most difficult design work: it must teach every foundational skill
> without feeling like a lesson, and it must create enough investment that the
> player commits to the journey ahead. Research on player retention shows that
> most players who leave a game do so in the first 30 minutes — not because
> the game is bad, but because onboarding failed to connect them.
>
> The scaffolding principle (Vygotsky's Zone of Proximal Development, adapted
> for game design): introduce each mechanic in isolation before combining it
> with others. A player cannot learn two skills simultaneously under pressure.
### What the Player Knows at Each Stage
| Time | What the Player Knows | What They Do Not Know Yet |
|------|-----------------------|--------------------------|
| [0 min] | [Literally nothing — treat this row as your most important UX audit. What can a player infer from the title screen alone?] | [Everything] |
| [5 min] | [Core movement verb, basic world reading] | [All progression systems, all secondary mechanics] |
| [15 min] | [Core interaction loop, first goal] | [Build depth, advanced mechanics, danger severity] |
| [30 min] | [Has made at least one strategic choice] | [Whether that choice was optimal] |
| [60 min] | [Has a working model of the core loop] | [Late-game depth, optional systems] |
### Mechanic Introduction Sequence
> The order mechanics are introduced is a design decision with real consequences.
> Introduce the most essential verb first. Introduce mechanics that modify other
> mechanics AFTER the base mechanic is internalized. Never introduce two new
> mechanics in the same encounter.
| Mechanic | Introduced At | Introduction Method | Stakes at Introduction |
|----------|--------------|--------------------|-----------------------|
| [Core movement / primary verb] | [e.g., First 30 seconds] | [Tutorial prompt / environmental design / NPC instruction] | [None — safe space to experiment] |
| [Primary interaction / action] | [e.g., First 2 minutes] | [Method] | [Low — reversible, forgiving window] |
| [First resource mechanic] | [e.g., 5 min] | [Method] | [Low — abundant at introduction] |
| [First strategic choice] | [e.g., 15 min] | [Method] | [Low — choice can be changed or revisited] |
| [First real failure risk] | [e.g., 20-30 min] | [Method] | [Moderate — player should feel genuine threat but have fair tools to respond] |
| [Add mechanic] | [Timing] | [Method] | [Stakes] |
### The First Failure
[Describe the intended design of the first moment the player can meaningfully
fail. This is one of the most important beats in the game.
A well-designed first failure teaches rather than punishes. The player should
be able to immediately identify what they did wrong and what they would do
differently. If the cause of failure is ambiguous, the player blames the game.
Answer: What causes the first failure? What does the player learn from it?
How quickly can they retry? What is the cost? Does the game provide any
feedback that bridges cause and effect?]
### When the Player First Feels Competent
[Identify the specific moment — not a vague window, but a specific beat —
where the player should shift from "learning" to "doing." This is the moment
of first competence: the first time their prediction about the game comes true,
or the first time they execute a plan and it works.
This moment must happen within the first hour. If it does not, the player
will not reach Phase 3 of the journey (First Mastery). Design this moment
deliberately — do not leave it to chance.
What is the moment? What systems create it? What does the player do to
trigger it? How does the game communicate that they have succeeded?]
---
## Difficulty Spikes and Valleys
> **Guidance**: A healthy difficulty curve follows a sawtooth pattern
> (Csikszentmihalyi's flow model applied to macro-structure): tension builds
> through a sequence, then releases at a milestone, then re-engages at a
> slightly higher baseline. Flat difficulty creates boredom; uninterrupted
> escalation creates fatigue.
>
> Spikes are intentional peaks that test accumulated skills. Valleys are
> intentional troughs that give the player space to breathe, experiment, and
> feel powerful before the next escalation. Both are designed, not emergent.
>
> "Recovery design" is critical: what happens immediately after a spike? The
> player should exit a hard moment feeling accomplished, not depleted. Give
> them a valley, a reward, or a narrative payoff.
| Name | Location in Game | Type | Purpose | Recovery Design |
|------|-----------------|------|---------|-----------------|
| [e.g., "The First Boss"] | [e.g., End of Area 1, ~1 hr] | [Spike] | [Tests all skills introduced in Area 1. Acts as a gate confirming the player is ready for increased complexity.] | [Post-boss: safe area, upgrade opportunity, story beat that provides emotional relief before Area 2 escalation begins.] |
| [e.g., "The Safe Zone"] | [e.g., Hub area between Areas 1 and 2, ~1.5 hrs] | [Valley] | [Player feels powerful from boss win. Space to experiment with build options before stakes rise.] | [N/A — this IS the recovery from the preceding spike.] |
| [e.g., "The Knowledge Wall"] | [e.g., Area 3 first encounter, ~4 hrs] | [Spike — knowledge type] | [Forces players to engage with a mechanic they may have been avoiding. Survival requires understanding it.] | [Clear feedback on what killed them. Tutorial hint surfaces on third failure. Mechanic becomes standard after this point.] |
| [e.g., "Pre-Climax Valley"] | [e.g., Just before final act, ~20 hrs] | [Valley] | [Emotional breathing room before the final escalation. Player reflects on how far they have come.] | [N/A — designed as relief before the finale's spike.] |
| [Add spike/valley] | [Location] | [Type] | [Purpose] | [Recovery] |
---
## Balancing Levers
> **Guidance**: Balancing levers are the specific values and parameters that
> tune difficulty at each phase. Centralizing them here makes it possible to
> tune the whole-game difficulty curve without hunting through individual GDDs.
> For each lever, the GDD that owns it should be cross-referenced.
>
> "Current setting" is the design intent at the time of writing — implementation
> values live in `assets/data/`. The tuning range is the safe operating range:
> values outside this range reliably break the intended experience.
| Lever | Phase(s) | Effect | Current Setting | Tuning Range | Notes |
|-------|----------|--------|----------------|-------------|-------|
| [Enemy health multiplier] | [All] | [Higher = longer fights = more resource pressure and execution time] | [1.0x] | [0.7x - 1.5x] | [Below 0.7x, fights end before player can read enemy patterns. Above 1.5x, attrition replaces skill.] |
| [Enemy aggression timer] | [Mid game onward] | [Time between enemy attacks; lower = less time to react] | [e.g., 2.0s] | [1.2s - 3.0s] | [Below 1.2s, reaction window is sub-human. Above 3.0s, encounters feel passive.] |
| [Resource drop rate] | [Early game] | [Lower = more resource pressure = punishes inefficiency harder] | [e.g., 1.5x baseline] | [0.8x - 2.0x] | [Onboarding generosity; reduces in mid-game as player skill assumed.] |
| [New mechanic introduction density] | [First hour] | [How many new concepts per minute of play; too high = cognitive overload] | [e.g., 1 new mechanic per 8 min] | [1 per 5 min (max) to 1 per 15 min (slow)] | [Above 1 per 5 min in early game causes retention drop. Below 1 per 15 min causes boredom.] |
| [Failure cost] | [All] | [Time lost on failure; higher = more punishing = more tension] | [e.g., 2 min setback] | [30s - 8 min] | [Must scale with encounter frequency. Frequent failures need fast recovery.] |
| [Add lever] | [Phase] | [Effect] | [Setting] | [Range] | [Notes] |
---
## Player Skill Assumptions
> **Guidance**: Every game implicitly assumes players develop a set of skills
> over the course of play. Making these assumptions explicit allows the team to
> verify that each skill is actually taught before it is tested, and that the
> gap between "introduced" and "tested hard" is long enough for internalization.
>
> A skill introduced and tested in the same encounter is a surprise difficulty
> spike. A skill assumed but never formally introduced is an undocumented knowledge
> wall. Both are fixable — but only if they are documented.
>
> "Taught by" refers to the mechanism: tutorial prompt, environmental design,
> safe practice opportunity, NPC instruction, or organic discovery.
>
> "Tested by" refers to the first encounter that REQUIRES this skill to survive
> without taking significant damage or cost.
| Skill | Introduced In | Expected Mastered By | Taught By | First Hard Test |
|-------|--------------|---------------------|-----------|-----------------|
| [Core movement / dodging] | [Tutorial area, 0-5 min] | [End of Area 1, ~1 hr] | [Safe practice zone with visible hazards] | [First Elite enemy, ~45 min] |
| [Resource management] | [First shop encounter, ~10 min] | [Mid game, ~4 hrs] | [Resource scarcity in Area 2 forces planning] | [Boss that requires consumables to survive efficiently] |
| [Build decision-making] | [First upgrade choice, ~20 min] | [End of mid game, ~10 hrs] | [Multiple playthroughs / community discussion / in-game build advisor] | [Endgame encounters that punish build incoherence] |
| [Enemy pattern reading] | [Area 1 basic enemies] | [Area 3, ~4 hrs] | [Enemy telegraphs visible and consistent from introduction] | [Elite enemy with 3+ distinct attack patterns] |
| [Add skill] | [When introduced] | [When mastered] | [Taught by] | [First hard test] |
---
## Accessibility Considerations
> **Guidance**: Accessibility in difficulty design is not about making the game
> easier — it is about ensuring players with different needs and skill profiles
> can reach the intended emotional experience. Be explicit about what CAN be
> adjusted and what CANNOT, and justify both.
>
> The principle from Self-Determination Theory: players need to feel competent.
> Accessibility options that help players feel competent without removing the
> feeling of agency are always worth including. Options that make competence
> meaningless undermine the core experience.
### What Can Be Adjusted
| Adjustment | Method | Effect on Experience | Tradeoff |
|-----------|--------|---------------------|----------|
| [e.g., Enemy speed reduction] | [Difficulty setting / accessibility menu] | [Lowers execution difficulty without changing knowledge or decision requirements] | [Reduces the tension of combat timing; acceptable for narrative players] |
| [e.g., Extended input windows] | [Accessibility menu] | [Allows players with motor impairments to achieve the same skill outcomes with more time] | [Minimal — skill expression preserved, threshold relaxed] |
| [e.g., Hint frequency] | [Settings toggle] | [Surfaces contextual guidance more or less aggressively based on player preference] | [Higher hints reduce knowledge difficulty; players who want to discover organically may feel over-guided] |
| [Add option] | [Method] | [Effect] | [Tradeoff] |
### What Cannot Be Adjusted (and Why)
| Fixed Element | Why It Cannot Change | Design Reasoning |
|--------------|---------------------|-----------------|
| [e.g., Permadeath in roguelike run] | [Removing it eliminates the resource pressure axis that all encounter balance is built around] | [The weight of each decision comes from permanence; without it, the core loop loses meaning] |
| [e.g., Core narrative pacing] | [Difficulty valleys are timed to story beats; adjustable pacing would decouple challenge from narrative intention] | [Story and difficulty are designed as one arc, not two independent tracks] |
| [Add fixed element] | [Why] | [Reasoning] |
---
## Cross-System Difficulty Interactions
> **Guidance**: When two systems operate simultaneously, their combined
> difficulty is often greater than the sum of their parts — or sometimes
> less. These interactions are frequently unintended and only surface during
> playtesting. Documenting anticipated interactions here creates a checklist
> for QA and playtest sessions.
>
> "Is this intended?" Yes means the interaction is a designed feature.
> No means it should be mitigated. Partial means the interaction is
> acceptable in small doses but problematic if it becomes the dominant
> experience.
| System A | System B | Combined Effect | Intended? |
|----------|----------|----------------|-----------|
| [Combat difficulty] | [Resource scarcity] | [Resource-poor players face combat encounters with fewer options, compounding difficulty for players already struggling. Can create a death spiral where failing creates worse conditions.] | [Partial — intended as stakes, not as a trap. Pity mechanics required to prevent unrecoverable states.] |
| [Build complexity] | [Time pressure] | [Players who are still learning their build take longer to make decisions under time pressure, increasing cognitive load beyond the intended challenge of either system alone.] | [No — reduce decision complexity demand in high time-pressure encounters.] |
| [New mechanic introduction] | [Resource pressure] | [Introducing a new system while the player is already under resource pressure forces them to learn and optimize simultaneously.] | [No — new mechanics should be introduced in low-resource-pressure environments.] |
| [Enemy density] | [Execution difficulty] | [High enemy counts with individually demanding enemies produce difficulty that scales exponentially, not linearly.] | [Partial — intended for optional challenge content only; not acceptable on the critical path.] |
| [Add System A] | [Add System B] | [Combined effect description] | [Yes / No / Partial] |
---
## Validation Checklist
> **Guidance**: These checkpoints structure playtesting sessions to verify
> the difficulty curve is achieving its intent. Each item should be checked
> with at least 3 playtester sessions before being marked complete. Note the
> playtester profile that revealed issues — difficulty problems are almost
> always player-profile-specific.
### Onboarding (0-30 min)
- [ ] Players with no prior genre experience complete the tutorial area without external help
- [ ] Zero players cite confusion about what they are supposed to be doing in the first 5 minutes
- [ ] At least one playtester spontaneously says "I want to see what's next" within 15 minutes
- [ ] First failure moment produces a visible learning response (player verbalizes what went wrong)
### Early Game (30 min - 2 hrs)
- [ ] Average player reaches the first competence moment within 60 minutes
- [ ] First major encounter (boss or equivalent) is passed within 3-5 attempts on average
- [ ] No player cites a mechanic introduced "too suddenly without warning"
- [ ] Players can describe their current goal without prompting
### Mid Game (2-10 hrs)
- [ ] Players discover at least one depth mechanic through organic play (without guide)
- [ ] Playtest sessions report "I want to try a different build / strategy next run"
- [ ] No single difficulty axis dominates player complaints — frustration is distributed
- [ ] Players who fail a mid-game encounter correctly identify the cause without being told
### Late Game (10+ hrs)
- [ ] Players report the final challenge feels like a culmination of everything they have learned
- [ ] Failure at late-game content does not feel unfair (even if it is hard)
- [ ] Players who complete the main content express a reason to continue playing
### Accessibility
- [ ] All listed accessibility options function without breaking encounter intent
- [ ] Players using accessibility settings report feeling competent, not patronized
- [ ] Fixed difficulty elements are encountered and accepted without negative reception from accessibility playtesters
---
## Open Questions
| Question | Owner | Deadline | Resolution |
|----------|-------|----------|-----------|
| [Is the onboarding ramp correctly calibrated for players without prior genre experience?] | [game-designer] | [Date] | [Unresolved — schedule genre-naive playtester sessions] |
| [Does the first boss represent the correct difficulty spike or is it a wall?] | [game-designer, systems-designer] | [Date] | [Unresolved — requires 5+ playtester sessions to establish average attempt count] |
| [Do any cross-system interactions produce unrecoverable states?] | [systems-designer] | [Date] | [Unresolved — requires targeted playtest with resource-constrained starting conditions] |
| [Add question] | [Owner] | [Date] | [Resolution] |

76
.claude/docs/templates/game-design-document.md vendored
View file

@ -91,6 +91,82 @@ value, the safe range, and what happens at the extremes.]
| Event | Visual Feedback | Audio Feedback | Priority |
|-------|----------------|---------------|----------|
## Game Feel
> **Why this section exists separately from Visual/Audio Requirements**: Visual/Audio
> Requirements document WHAT feedback events occur (tables of events mapped to assets).
> Game Feel documents HOW the mechanic feels to operate — the responsiveness, weight,
> snap, and kinesthetic quality of the interaction. These are design targets for timing,
> frame data, and physical sensation of control. Game feel must be specified at design
> time because it drives animation budgets, input handling architecture, and hitbox
> timing. Retrofitting feel targets after implementation is expensive and often requires
> fundamental rework.
### Feel Reference
[Name a specific game, mechanic, or moment that captures the target feel. Be precise —
cite the exact mechanic, not just the game. Explain what quality you are borrowing.
Optionally include an anti-reference (what this should NOT feel like).]
> Example: "Should feel like Dark Souls weapon swings — weighty, committed, and
> telegraphed, but satisfying on contact. NOT floaty like early Halo melee."
### Input Responsiveness
[Maximum acceptable latency from player input to visible/audible response, per action.]
| Action | Max Input-to-Response Latency (ms) | Frame Budget (at 60fps) | Notes |
|--------|-----------------------------------|------------------------|-------|
| [Primary action] | [e.g., 50ms] | [e.g., 3 frames] | |
| [Secondary action] | | | |
### Animation Feel Targets
[Frame data targets for each animation in this mechanic. Startup = windup before the
action has any effect. Active = frames when the action is "happening" (hitbox live,
ability firing, etc.). Recovery = committed/vulnerable frames after the action resolves.]
| Animation | Startup Frames | Active Frames | Recovery Frames | Feel Goal | Notes |
|-----------|---------------|--------------|----------------|-----------|-------|
| [e.g., Light attack] | | | | [e.g., Snappy, low commitment] | |
| [e.g., Heavy attack] | | | | [e.g., Weighty, high commitment] | |
### Impact Moments
[Defines the punctuation of the mechanic — the moments of peak feedback intensity that
make actions feel consequential. Every high-stakes event should have at least one entry.]
| Impact Type | Duration (ms) | Effect Description | Configurable? |
|-------------|--------------|-------------------|---------------|
| Hit-stop (freeze frames) | [e.g., 80ms] | [Freeze both objects on contact] | Yes |
| Screen shake | [e.g., 150ms] | [Directional, decaying] | Yes |
| Camera impact | | | |
| Controller rumble | | | |
| Time-scale slowdown | | | |
### Weight and Responsiveness Profile
[A short prose description of the overall feel target. Answer the following:]
- **Weight**: Does this feel heavy and deliberate, or light and reactive?
- **Player control**: How much does the player feel in control at every moment?
(High control = can course-correct mid-action; Low control = committed, momentum-based)
- **Snap quality**: Does this feel crisp and binary, or smooth and analog?
- **Acceleration model**: Does movement/action start instantly (arcade feel) or
ramp up from zero (simulation feel)? Same question for deceleration.
- **Failure texture**: When the player makes an error, does the mechanic feel fair
or punishing? What is the read on WHY they failed?
### Feel Acceptance Criteria
[Specific, testable criteria a playtester can verify without measurement instruments.
These are subjective targets stated precisely enough to get consistent verdicts.]
- [ ] [e.g., "Combat feels impactful — playtesters comment on weight unprompted"]
- [ ] [e.g., "No reviewer uses the words 'floaty', 'slippery', or 'unresponsive'"]
- [ ] [e.g., "Input latency is imperceptible at target 60fps framerate"]
- [ ] [e.g., "Hit-stop reads as satisfying, not as lag or stutter"]
## UI Requirements
[What information needs to be displayed to the player and when?]

505
.claude/docs/templates/hud-design.md vendored Normal file
View file

@ -0,0 +1,505 @@
# HUD Design: [Game Name]
> **Status**: Draft | In Review | Approved | Implemented
> **Author**: [Name or agent — e.g., ui-designer]
> **Last Updated**: [Date]
> **Game**: [Game name — this is a single document per game, not per element]
> **Platform Targets**: [All platforms this HUD must work on — e.g., PC, PS5, Xbox Series X, Steam Deck]
> **Related GDDs**: [Every system that exposes information through the HUD — e.g., `design/gdd/combat.md`, `design/gdd/progression.md`, `design/gdd/quests.md`]
> **Accessibility Tier**: Basic | Standard | Comprehensive | Exemplary
> **Style Reference**: [Link to art bible HUD section if it exists — e.g., `design/gdd/art-bible.md § HUD Visual Language`]
> **Note — Scope boundary**: This document specifies all elements that overlay the
> game world during active gameplay — health bars, ammo counters, minimaps, quest
> trackers, subtitles, damage numbers, and notification toasts. For menu screens,
> pause menus, inventory, and dialogs that the player navigates explicitly, use
> `ux-spec.md` instead. The test: if it appears while the player is directly
> controlling their character, it belongs here.
---
## 1. HUD Philosophy
> **Why this section exists**: The HUD design philosophy is not decoration — it is a
> design constraint that every subsequent decision is measured against. Without a
> philosophy, individual elements get added on request ("the quest tracker wants a
> bigger icon") without any principled way to push back. With a philosophy, there is
> a shared, explicit standard. More importantly, the philosophy prevents the HUD from
> slowly growing to cover the game world while each individual addition seemed
> reasonable in isolation. Write this before specifying any elements.
**What is this game's relationship with on-screen information?**
[One paragraph. This is a design statement, not a description of features. Consider
the game's genre, pacing, and player fantasy. A stealth game's HUD philosophy might
be: "The world is the interface. If the player has to look away from the environment
to survive, the HUD has failed." A tactics game might say: "Complete situational
awareness is the game. The HUD is not an overlay — it is the battlefield."
Reference comparable games if helpful, but describe your specific stance:
Example — diegetic-first action RPG: "We treat screen information as a concession,
not a feature. Every HUD element must earn its pixel space by answering the question:
would the player make demonstrably worse decisions without this information visible?
If the answer is 'they'd adapt,' we put it in the environment instead."]
**Visibility principle** — when in doubt, show or hide?
[State the default resolution for ambiguous cases. Options:
- Default to HIDE: information is available on demand (e.g., Dark Souls — no quest tracker, no minimap, stats are in a menu)
- Default to SHOW: players prefer to be informed; cluttered is better than uncertain
- Default to CONTEXTUAL: information appears when it becomes relevant and fades when it does not
Most games benefit from contextual defaults. State your game's default clearly so every element decision is consistent.]
**The Rule of Necessity for this game**:
[Complete this sentence: "A HUD element earns its place when ______________."
Example: "...the player would have to stop playing to find the same information
elsewhere, or would make meaningfully worse decisions without it."
Example: "...removing it in playtesting causes measurable frustration or confusion
in more than 25% of testers within the first hour of play."
This rule is the veto power over feature requests to add HUD elements. Document it
so it can be cited in design reviews.]
---
## 2. Information Architecture
> **Why this section exists**: Before specifying any HUD element's visual design,
> position, or behavior, you must answer a more fundamental question: should this
> information be on the HUD at all? This section is a forcing function — it requires
> you to categorize EVERY piece of information the game world generates and make an
> explicit, intentional decision about how each is presented. "We'll figure that out
> later" is how games end up with 18 elements competing for the player's peripheral
> vision. This table is the master inventory of game information, not just HUD information.
| Information Type | Always Show | Contextual (show when relevant) | On Demand (menu/button) | Hidden (environmental / diegetic) | Reasoning |
|-----------------|-------------|--------------------------------|------------------------|----------------------------------|-----------|
| [Health / Vitality] | [X if action game — player needs constant awareness] | [X if exploration game — show only when injured] | [ ] | [ ] | [Example: always visible because health decisions (retreat, heal) must be instant in combat] |
| [Primary resource (mana / stamina / ammo)] | [ ] | [X — show when resource is being consumed or is critically low] | [ ] | [ ] | [Example: contextual because stable resource levels are not decision-relevant] |
| [Secondary resource (currency / materials)] | [ ] | [ ] | [X — check in inventory] | [ ] | [Example: on-demand because resource totals don't affect immediate gameplay decisions] |
| [Minimap / Compass] | [X] | [ ] | [ ] | [ ] | [Example: always visible because navigation decisions are constant during exploration] |
| [Quest objective] | [ ] | [X — show when objective changes or player is near it] | [ ] | [ ] | [Example: contextual — player knows their objective; only remind at key moments] |
| [Enemy health bar] | [ ] | [X — show only during combat encounters] | [ ] | [ ] | [Example: contextual because enemy health is irrelevant outside combat] |
| [Status effects (buffs/debuffs)] | [ ] | [X — show when active] | [ ] | [ ] | [Example: contextual because status effects only affect decisions when present] |
| [Dialogue subtitles] | [X when dialogue is playing] | [ ] | [ ] | [ ] | [Example: always show while dialogue is active — accessibility requirement] |
| [Combo / streak counter] | [ ] | [X — show while combo is active, hide on reset] | [ ] | [ ] | [Example: contextual because it communicates active performance, not baseline state] |
| [Timer] | [ ] | [X — show only in timed sequences] | [ ] | [ ] | [Example: contextual because timers only exist in specific encounter types] |
| [Tutorial prompts] | [ ] | [X — show for first-time situations only] | [ ] | [ ] | [Example: contextual and one-time; never repeat to experienced players] |
| [Score / points] | [ ] | [X — show in score-relevant modes only] | [ ] | [ ] | [Example: contextual by game mode; hidden in modes where score is irrelevant] |
| [XP / level progress] | [ ] | [ ] | [X — available via character screen] | [ ] | [Example: on-demand because progression does not affect in-moment gameplay decisions] |
| [Waypoint / objective marker] | [ ] | [X — show when player is navigating to objective] | [ ] | [ ] | [Example: contextual — suppress during cutscenes, cinematic moments, and free exploration] |
---
## 3. Layout Zones
> **Why this section exists**: The game world is the primary content — the HUD is a
> frame around it. Before placing any element, divide the screen into named zones
> with explicit positions and safe zone margins. This section prevents two failure
> modes: (1) elements placed ad-hoc until the screen is cluttered, and (2) elements
> that overlap platform-required safe zones and get rejected in certification.
> Every element in Section 4 must be assigned to a zone defined here.
### 3.1 Zone Diagram
```
[Draw your HUD layout zones. Customize this to match your game's actual layout.
Axes represent approximate screen percentage. Adjust zone names and sizes.]
0% 100%
┌──────────────────────────────────────────────────┐ 0%
│ [SAFE MARGIN — 10% from edge on all sides] │
│ ┌────────────────────────────────────────────┐ │
│ │ [TOP-LEFT] [TOP-CENTER] [TOP-RIGHT] │ ~15%
│ │ Health, resource Quest name Ammo, magazine │
│ │ │ │
│ │ │ │
│ │ [CENTER-SCREEN] │ │ ~50%
│ │ Crosshair / reticle │ │
│ │ (minimize HUD here) │ │
│ │ │ │
│ │ │ │
│ │ [BOTTOM-LEFT] [BOTTOM-CENTER] [BOTTOM-RIGHT] │ ~85%
│ │ Minimap Subtitles Notifications │
│ │ Ability icons Tutorial prompts │ │
│ └────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────┘ 100%
```
> Rule for zone placement: the center 40% of the screen (both horizontally and
> vertically) is the player's primary focus area. Keep this zone as clear as
> possible at all times. HUD elements that appear in the center zone — crosshairs,
> interaction prompts, hit markers — must be minimal, high-contrast, and brief.
### 3.2 Zone Specification Table
| Zone Name | Screen Position | Safe Zone Compliant | Primary Elements | Max Simultaneous Elements | Notes |
|-----------|----------------|---------------------|-----------------|--------------------------|-------|
| [Top Left] | [Top-left corner, within safe margin] | [Yes — 10% from top, 10% from left] | [Health bar, stamina bar, shield bar] | [3] | [Vital status — player's own resources. Priority zone for player state.] |
| [Top Center] | [Top edge, centered horizontally] | [Yes — 10% from top] | [Quest objective, area name (on enter)] | [1 — only one message at a time] | [Use for narrative context, not mechanical information. Keep text minimal.] |
| [Top Right] | [Top-right corner, within safe margin] | [Yes — 10% from top, 10% from right] | [Ammo count, ability cooldowns] | [2] | [Weapon/ability state. Most relevant during active combat.] |
| [Center] | [Screen center ±15%] | [N/A — not a margin zone] | [Crosshair, interaction prompt, hit marker] | [1 active at a time] | [CRITICAL: Nothing persistent here. Only momentary indicators.] |
| [Bottom Left] | [Bottom-left corner, within safe margin] | [Yes — 10% from bottom, 10% from left] | [Minimap, ability icons] | [2] | [Navigation and ability readout. Small, non-intrusive.] |
| [Bottom Center] | [Bottom edge, centered horizontally] | [Yes — 10% from bottom] | [Subtitles, tutorial prompts] | [2 — subtitle + tutorial may coexist] | [Highest-priority accessibility zone. Never place other elements here.] |
| [Bottom Right] | [Bottom-right corner, within safe margin] | [Yes — 10% from bottom, 10% from right] | [Notification toasts, pick-up feedback] | [3 stacked] | [Transient notifications. Stack vertically. Oldest disappears first.] |
**Safe zone margins by platform**:
| Platform | Top | Bottom | Left | Right | Notes |
|----------|-----|--------|------|-------|-------|
| [PC — windowed] | [0% — no safe zone required] | [0%] | [0%] | [0%] | [But respect minimum resolution — elements must not crowd at 1280x720] |
| [PC — fullscreen] | [3%] | [3%] | [3%] | [3%] | [Slight margin for 4K TV-connected PCs] |
| [Console — TV] | [10%] | [10%] | [10%] | [10%] | [Action-safe zone for broadcast-spec TVs. Some TVs overscan beyond this.] |
| [Steam Deck] | [5%] | [5%] | [5%] | [5%] | [Small screen; safe zone is smaller but crowding risk is higher] |
| [Mobile — portrait] | [15% top] | [10% bottom] | [5%] | [5%] | [15% top avoids notch/camera cutout on most devices] |
| [Mobile — landscape] | [5%] | [5%] | [15% left] | [15% right] | [Thumb placement on landscape — side zones are obscured by hands] |
---
## 4. HUD Element Specifications
> **Why this section exists**: Each HUD element needs its own specification to be
> built correctly. Ad-hoc implementation of HUD elements produces inconsistent
> sizing, mismatched update frequencies, missing urgency states, and accessibility
> failures. This section is the implementation brief for every element — fill it
> completely before any element moves into development.
### 4.1 Element Overview Table
> One row per HUD element. This is the master inventory for implementation planning.
| Element Name | Zone | Always Visible | Visibility Trigger | Data Source | Update Frequency | Max Size (% screen W) | Min Readable Size | Overlap Priority | Accessibility Alt |
|-------------|------|---------------|-------------------|-------------|-----------------|----------------------|------------------|-----------------|------------------|
| [Health Bar] | [Top Left] | [Yes] | [N/A] | [PlayerStats] | [On value change] | [20%] | [120px wide] | [1 — highest] | [Numerical text label showing current/max: "80/100"] |
| [Stamina Bar] | [Top Left] | [No — context] | [Show when consuming stamina; hide 3s after full] | [PlayerStats] | [Realtime during use] | [15%] | [80px wide] | [2] | [Numerical label, or hide if full (accessible assumption)] |
| [Shield Indicator] | [Top Left] | [No — context] | [Show when shield is active or recently hit] | [PlayerStats] | [On value change] | [20%] | [120px wide] | [3] | [Numerical label. Must not use color alone — add shield icon.] |
| [Ammo Counter] | [Top Right] | [No — context] | [Show when weapon is equipped; hide when unarmed] | [WeaponSystem] | [On fire / on reload] | [10%] | ["88/888" readable at game's min resolution] | [4] | [Text-only fallback: "32 / 120"] |
| [Minimap] | [Bottom Left] | [Yes] | [N/A — but suppressed in cinematic mode] | [NavigationSystem] | [Realtime] | [18%] | [150x150px] | [5] | [Cardinal direction compass strip as fallback; must be toggleable] |
| [Quest Objective] | [Top Center] | [No — context] | [Show on objective change; show when near objective location; hide after 5s] | [QuestSystem] | [On event] | [30%] | [Legible at body text size] | [6] | [Read aloud on objective change via screen reader] |
| [Crosshair] | [Center] | [No — context] | [Show when ranged weapon equipped; hide in melee or unarmed] | [WeaponSystem / AimSystem] | [Realtime] | [3%] | [12px diameter minimum] | [1 — center zone priority] | [Reduce motion: static crosshair only. Option to enlarge.] |
| [Interaction Prompt] | [Center] | [No — context] | [Show when player is within interaction range of an interactive object] | [InteractionSystem] | [On enter/exit interaction range] | [15%] | [24px icon + readable text] | [2 — center zone] | [Text description of interaction always present, not icon-only] |
| [Subtitles] | [Bottom Center] | [No — always on when dialogue plays, if setting enabled] | [Show during any voiced line or ambient dialogue] | [DialogueSystem] | [Per dialogue line] | [60%] | [Minimum 24px font] | [1 — highest in zone] | [This IS the accessibility feature — see Section 8 for subtitle spec] |
| [Damage Numbers] | [World-space / anchored to entity] | [No — context] | [Show on any damage event; duration 800ms] | [CombatSystem] | [On event] | [5% per number] | [18px minimum] | [3] | [Option to disable; numbers can overwhelm for photosensitive players] |
| [Status Effect Icons] | [Top Left — below health bar] | [No — context] | [Show when any status effect is active on player] | [StatusSystem] | [On effect add/remove] | [3% per icon] | [24px per icon] | [3] | [Icon + text label on hover/focus. Never icon-only.] |
| [Notification Toast] | [Bottom Right] | [No — event-driven] | [On loot, XP gain, achievement, quest update] | [Multiple — see Section 6] | [On event] | [25%] | [Legible at body text size] | [7 — lowest] | [Queued; never overlapping. Read by screen reader if subtitle mode on.] |
### 4.2 Element Detail Blocks
> For each element in the table above, write a detail block. Copy and complete
> one block per element.
---
**Health Bar**
- Visual description: [Horizontal fill bar. Left-to-right fill direction. Segmented at 25/50/75% to aid reading at a glance. Background: dark semi-transparent (40% opacity). Fill color: context-dependent — see Urgency States.]
- Data displayed: [Current HP as fill percentage. Numerical value displayed as text below bar at all times: "80 / 100".]
- Update behavior: [Bar fill decreases or increases smoothly using a lerp over 150ms per change. Large damage (>25% single hit) triggers a brief flash (1 frame white, then drain).]
- Urgency states:
- Normal (>50% HP): [Green fill, no special behavior]
- Caution (25–50% HP): [Yellow fill, low warning pulse every 4 seconds]
- Critical (<25% HP): [Red fill, persistent slow pulse (1 Hz), vignette appears at screen edges]
- Zero (0% HP): [Bar empties and turns grey; death state begins]
- Interaction: [Display only. Not interactive. Player cannot click, hover, or focus this element as an action target.]
- Player customization: [Opacity adjustable (see Section 7 Tuning Knobs). Can be repositioned to any corner by player in accessibility settings.]
---
**Minimap**
- Visual description: [Circular mask, radius = 75px at reference resolution 1920x1080. Player icon at center. North always up unless player has unlocked "Rotate minimap" setting. Range = configurable, default 80 world units radius.]
- Data displayed: [Player position, nearby enemies (if detection perk unlocked), quest markers within range, points of interest icons, traversal obstacles (walls, drops).]
- Update behavior: [Realtime. Updates every frame. Enemy icons fade in/out as they enter/leave detection range over 300ms.]
- Urgency states: [None for the map itself. Enemy icons turn red when they are in combat-alert state.]
- Interaction: [Not interactive in-game. Press dedicated Map button to open the full map screen (separate UX spec).]
- Player customization: [Size: S/M/L (70/90/110px radius). Opacity: 30–100%. Rotation: locked-north or player-relative. Can be disabled entirely (compass strip shows as fallback).]
---
**[Repeat this block for every element in Section 4.1]**
---
## 5. HUD States by Gameplay Context
> **Why this section exists**: The HUD is not a static overlay — it is a dynamic
> system that must adapt to what the player is doing. A HUD designed only for
> standard gameplay will look wrong in cutscenes, feel cluttered in exploration,
> and occlude critical information in boss fights. This section defines the
> transformations the HUD undergoes in each gameplay context. It is also the spec
> for the system that manages HUD visibility — the HUD state machine.
| Context | Elements Shown | Elements Hidden | Elements Modified | Transition Into This State |
|---------|---------------|-----------------|------------------|---------------------------|
| [Exploration — no threats] | [Minimap, Quest Objective (faded, 60%), Subtitles (if active)] | [Ammo Counter, Crosshair, Damage Numbers, Status Effects (if none active)] | [Health Bar fades to 40% opacity — visible but not dominant] | [Fade transition, 500ms, when no enemies detected for 10s] |
| [Combat — active threat] | [Health Bar (full opacity), Stamina Bar (when used), Ammo Counter, Crosshair, Damage Numbers, Status Effects, Enemy Health Bars] | [Quest Objective (temporarily hidden), Notification Toasts (paused queue)] | [Minimap scales down 15% and raises opacity to 100%] | [Immediate snap in on first enemy detection — no fade. Combat readiness requires instant info.] |
| [Dialogue / Cutscene] | [Subtitles, Dialogue speaker name] | [All gameplay HUD elements: health, ammo, minimap, crosshair, damage numbers] | [N/A] | [All gameplay elements fade out over 300ms when cutscene flag is set] |
| [Cinematic (scripted camera sequence)] | [Subtitles only] | [Everything else including speaker name] | [Letterbox bars appear (if applicable to this game's style)] | [Immediate on cinematic flag; letterbox slides in from top/bottom over 400ms] |
| [Inventory / Menu open] | [None — inventory renders full-screen or as overlay] | [All HUD elements] | [Game world visible but paused behind inventory screen] | [All HUD elements hide over 150ms as menu opens] |
| [Death / Respawn pending] | [Death screen overlay — separate spec] | [All gameplay HUD elements] | [Screen desaturates and darkens over 800ms] | [Death state begins when HP reaches 0 — HUD elements fade over 600ms] |
| [Loading / Transition] | [Loading indicator, tip text] | [All gameplay HUD elements] | [N/A] | [Instant on level transition trigger] |
| [Tutorial — new mechanic] | [Standard context HUD + Tutorial Prompt overlay] | [Nothing additional hidden] | [Tutorial prompt dims background subtly to draw attention to prompt] | [Tutorial system fires ShowTutorial event; prompt fades in over 200ms] |
| [Boss Encounter] | [Boss health bar appears (large, bottom of screen or top center), all combat elements] | [Quest Objective] | [Boss bar renders in a distinct visual style — must not be confused with player health] | [Boss health bar slides in on boss encounter trigger over 400ms] |
---
## 6. Information Hierarchy
> **Why this section exists**: Not all HUD information is equally important. When
> screen space is limited, when the player is under high stress, or when elements
> compete for the same zone, there must be a principled priority order that governs
> which elements survive and which get suppressed. This section formalizes that
> hierarchy so it can be enforced systematically and not just "feels obvious" decisions
> made at implementation time.
| Element | Priority Tier | Reasoning | What Replaces It If Hidden |
|---------|--------------|-----------|---------------------------|
| [Subtitles] | [MUST KEEP — never hide during dialogue] | [Accessibility requirement. Legal requirement in some markets. Story clarity.] | [N/A — nothing replaces subtitles] |
| [Health Bar] | [MUST KEEP — during any state where the player can be damaged] | [Without health visibility, survival decisions become impossible] | [Auditory cues (heartbeat, breathing) supplement but do not replace] |
| [Crosshair] | [MUST KEEP — while aiming with a ranged weapon] | [Targeting without a crosshair is a precision failure, not a difficulty feature] | [Alternative: dot-only mode for minimalists; never fully hidden while aiming] |
| [Interaction Prompt] | [MUST KEEP — when player is in interaction range] | [Without it, interactive objects are invisible to the player] | [Environmental visual cues can supplement but interaction affordance must be explicit] |
| [Ammo Counter] | [SHOULD KEEP] | [Low ammo decisions (switch weapon, reload) require awareness; can be contextual] | [Auditory "click" on empty chamber is acceptable fallback for experienced players] |
| [Minimap] | [SHOULD KEEP] | [Navigation requires spatial awareness; loss forces repeated map opens] | [Compass strip (simplified directional indicator) is acceptable fallback] |
| [Status Effects] | [SHOULD KEEP — while active] | [Active debuffs change what actions are viable; invisible debuffs feel unfair] | [Character animation states can partially communicate status effects (limping, sparks)] |
| [Quest Objective] | [CAN HIDE] | [Player can hold objective in memory for extended periods; contextual is correct default] | [Player remembers objective from context] |
| [Damage Numbers] | [CAN HIDE] | [Feedback element, not decision-critical. Many players turn these off.] | [Hit sounds and enemy reactions communicate hit registration] |
| [Notification Toasts] | [CAN HIDE in high-intensity moments] | [Mid-combat "You gained 50 XP" is noise, not signal. Queue and show after combat.] | [Queue held and released when combat ends] |
| [Combo Counter] | [ALWAYS HIDE when combo resets or player is not attacking] | [Stale combo information is actively misleading] | [N/A — simply hidden] |
---
## 7. Visual Budget
> **Why this section exists**: Without explicit budget constraints, HUD elements
> accumulate until the game world is nearly invisible. These numbers are hard limits,
> not guidelines. Every element addition that would breach a limit requires explicit
> approval and must displace or reduce an existing element.
| Budget Constraint | Limit | Measurement Method | Current Estimate | Status |
|------------------|-------|--------------------|-----------------|--------|
| Maximum simultaneous active HUD elements | [8] | [Count all visible, non-faded elements at any one frame] | [TBD — verify at implementation] | [To verify] |
| Maximum % of screen occupied by HUD (exploration mode) | [12%] | [Pixel area of all HUD elements / total screen pixels] | [TBD] | [To verify] |
| Maximum % of screen occupied by HUD (combat mode) | [22%] | [Same method — combat adds ammo, crosshair, enemy bars] | [TBD] | [To verify] |
| Maximum % of center screen zone (40% of screen W/H) occupied | [5%] | [Only crosshair and interaction prompt allowed here] | [TBD] | [To verify] |
| Minimum contrast ratio — HUD text on any background | [4.5:1 (WCAG AA)] | [Measured against the darkest and lightest game world areas the element will appear over] | [TBD] | [To verify] |
| Maximum opacity for HUD background panels | [65%] | [Opacity of any panel behind HUD text — must preserve world visibility through panel] | [TBD] | [To verify] |
| Minimum HUD element size at minimum supported resolution | [40px for icons, 18px for text] | [Measure at lowest target resolution] | [TBD] | [To verify] |
> **How to apply these budgets**: For every new HUD element proposed during
> production, require the proposer to state (1) which budget line it affects,
> (2) what the new total will be, and (3) what existing element will be reduced or
> made contextual to stay within budget. "It's a small icon" is not an analysis.
---
## 8. Feedback & Notification Systems
> **Why this section exists**: Notifications are the most frequently-added and
> worst-controlled part of most HUDs. Every system wants to tell the player
> something. Without explicit rules about notification priority, stacking limits,
> and queue behavior, the notification zone becomes a firehose of overlapping
> toasts that players learn to ignore entirely. This section establishes the
> notification contract for all systems.
| Notification Type | Trigger System | Screen Position | Duration (ms) | Animation In / Out | Max Simultaneous | Priority | Queue Behavior | Dismissible? |
|------------------|---------------|-----------------|--------------|-------------------|-----------------|----------|---------------|-------------|
| [Item Pickup] | [InventorySystem] | [Bottom Right — toast] | [2000] | [Slide in from right 200ms / fade out 300ms] | [3 stacked] | [Low] | [FIFO queue; older toasts pushed up as new ones enter] | [No — auto-dismiss] |
| [XP Gain] | [ProgressionSystem] | [Bottom Right — toast, below item toasts] | [1500] | [Fade in 150ms / fade out 300ms] | [1 — XP messages merge: "XP +150"] | [Very Low — suppress during combat, queue for post-combat] | [Combat-aware queue] | [No] |
| [Level Up] | [ProgressionSystem] | [Center screen — persistent until dismissed] | [Persistent — requires input to dismiss] | [Scale up from 80% + fade in 400ms] | [1] | [High — interrupts normal toasts] | [Pauses all other notifications until dismissed] | [Yes — any input] |
| [Quest Update] | [QuestSystem] | [Top Center] | [4000] | [Slide down from top 250ms / fade out 400ms] | [1 — top center is single-message zone] | [Medium] | [If quest update arrives while previous is visible, extend duration by 2000ms; do not stack] | [No] |
| [Objective Complete] | [QuestSystem] | [Top Center] | [3000] | [Same as Quest Update but with additional completion sound] | [1] | [Medium-High — preempts Quest Update] | [Preempts any queued top-center message] | [No] |
| [Critical Warning (low health, hazard)] | [CombatSystem / EnvironmentSystem] | [Screen edge vignette + text at center-bottom] | [Persistent while condition active] | [Fade in 200ms; fades out 500ms when condition clears] | [1 per warning type] | [Critical — never suppressed] | [Renders immediately, bypasses all queues] | [No] |
| [Achievement Unlocked] | [AchievementSystem] | [Bottom Right — distinct from item toasts] | [4000] | [Slide in from right with icon expansion 300ms / fade out 400ms] | [1] | [Low] | [Queues behind item toasts; never more than one achievement toast at a time] | [No] |
| [Hint / Tutorial] | [TutorialSystem] | [Bottom Center] | [Persistent — until player performs the action or dismisses] | [Fade in 300ms] | [1] | [Medium] | [Only one tutorial hint at a time; queue others] | [Yes — B button / Esc] |
**Notification queue rules**:
1. Combat-aware queue: notifications tagged as Low priority are queued, not displayed, when the player is in combat state. The queue is flushed in a batch when the player exits combat, with a max of 3 items displayed in sequence.
2. Merge rule: identical notification types that fire within 500ms of each other are merged into a single notification with a combined value (e.g., "Item Pickup x3" rather than three separate toasts).
3. Critical notifications (health warning, environmental hazard) are never queued, never merged, and always displayed immediately regardless of combat state or existing notifications.
---
## 9. Platform Adaptation
> **Why this section exists**: A HUD designed at 1920x1080 on a monitor may be
> illegible on a 55-inch TV at 4K, broken at 1280x720 on Steam Deck, or hidden
> behind a notch on mobile. Platform adaptation is not optional post-ship work —
> it is a design requirement that must be specified before implementation so the
> architecture can support it from the start. Every platform listed here requires
> explicit layout testing before certification.
| Platform | Safe Zone | Resolution Range | Input Method | HUD-Specific Notes |
|----------|-----------|-----------------|-------------|-------------------|
| [PC — Windows, 1920x1080 reference] | [3% margin] | [1280x720 min to 3840x2160 max] | [Mouse + keyboard, controller optional] | [HUD must scale correctly at all resolutions. Test at 1280x720 — minimum before cert. Consider ultrawide (21:9) — minimap must not stretch.] |
| [PC — Steam Deck, 1280x800] | [5% margin] | [Fixed 1280x800] | [Controller + touchscreen] | [Smaller screen means minimum text sizes are critical. Test ALL elements at this resolution. Touch targets irrelevant (controller-only by default).] |
| [PlayStation 5 / Xbox Series X] | [10% margin] | [1080p to 4K] | [Controller] | [Console certification requires TV safe zone compliance. Action-safe is 90% of screen area. Test on a real TV, not a monitor — overscan behavior differs.] |
| [Mobile — iOS / Android] | [15% top, 10% other sides] | [360x640 min to 414x896 common] | [Touch] | [Notch/camera cutout avoidance at top. Bottom home indicator zone avoidance. Portrait and landscape layouts may differ significantly — specify both.] |
**HUD repositionability requirement**: Players must be able to reposition at minimum the following elements using an in-game HUD layout editor (required for accessibility compliance on console):
- Health bar
- Minimap
- Ability bar (if present)
Repositioning saves to player profile, not to a single slot. Applies across play sessions.
---
## 10. Accessibility — HUD Specific
> **Why this section exists**: HUD accessibility failures are the most visible
> accessibility failures in games — players encounter the HUD in every session,
> in every gameplay moment. Color-blind failures, illegible text at minimum scale,
> and inability to disable distracting animations are among the top accessibility
> complaints in game reviews. This section defines HUD-specific requirements; refer
> to the project's `docs/accessibility-requirements.md` for the full project standard.
### 10.1 Colorblind Modes
| Element | Color-Only Information Risk | Colorblind Mode Fix |
|---------|----------------------------|---------------------|
| [Health bar fill] | [Red = low health uses red/green distinction] | [Add icon pulse + vignette as non-color indicators. Red fill is supplemental, not sole indicator.] |
| [Damage numbers] | [Red = taken, green = healed] | [Add minus (-) prefix for damage, plus (+) for healing. Symbols, not color.] |
| [Enemy health bars] | [If colored by faction or threat level] | [Add text label or icon badge for faction/threat level. Never color-only.] |
| [Status effect icons] | [If icon tint communicates status type] | [All status icons must have distinct shapes, not just distinct colors. Shape encodes meaning; color is secondary.] |
| [Minimap icons] | [If player vs. enemy vs. objective distinguished by color] | [Distinct icon shapes: circle = player, triangle = enemy, star = objective. Color supplements shape.] |
### 10.2 Text Scaling
[Describe what happens when the player sets the UI text scale to 150% (the maximum required for your Accessibility Tier). Which elements reflow? Which elements clip? Which elements are architecturally blocked from scaling (e.g., fixed-size canvases)?
Example: "Health bar numerical label grows with text scale — bar expands slightly to accommodate. Quest objective text wraps at 150% scale — verify Top Center zone can accommodate two-line objectives. Damage numbers do not scale (they are world-space, not screen-space) — this is an accepted limitation documented here."]
**Text scaling test matrix**:
| Element | 100% (baseline) | 125% | 150% | Overflow behavior |
|---------|----------------|------|------|-------------------|
| [Health bar label] | [Pass] | [Pass] | [TBD] | [Bar expands; does not overlap stamina bar] |
| [Quest objective text] | [Pass] | [TBD] | [TBD] | [Wraps to second line; zone height expands] |
| [Notification toast text] | [Pass] | [TBD] | [TBD] | [Toast width expands to max 35% screen width, then wraps] |
| [Subtitle text] | [Pass] | [TBD] | [TBD] | [Dedicated subtitle zone — must accommodate scale] |
### 10.3 Motion Sensitivity
| Animation / Motion Element | Severity | Disabled by Reduced Motion Setting? | Replacement Behavior |
|---------------------------|----------|-------------------------------------|---------------------|
| [Health bar low-HP pulse] | [Mild] | [Yes] | [Solid fill, no pulse. Vignette remains as it is less likely to trigger sensitivity.] |
| [Screen edge vignette] | [Moderate] | [Optional — separate toggle] | [Replace with static darkened corners at 30% opacity] |
| [Damage numbers float upward] | [Mild] | [Yes] | [Instant appear/disappear in place, no float] |
| [Notification toast slide-in] | [Mild] | [Yes] | [Instant appear at final position] |
| [Level up center animation] | [High] | [Yes — required] | [Static level up card, no scale animation, no particle effects] |
| [Combo counter scale pulse] | [Mild] | [Yes] | [Number increments without scale animation] |
### 10.4 Subtitles Specification
> Subtitles are the highest-impact accessibility feature in the HUD. Specify them
> with the same rigor as the rest of the HUD. Do not leave subtitle behavior to
> implementation discretion.
- **Default setting**: [ON or OFF — document your game's default and the rationale. Industry standard is ON by default.]
- **Position**: Bottom Center zone, centered horizontally, above the bottom safe zone margin
- **Max characters per line**: [42 characters — the readable limit for subtitle lines at minimum text size on TV viewing distance]
- **Max simultaneous lines**: [2 lines before scrolling — do not display more than 2 lines at once]
- **Speaker identification**: [Speaker name displayed in color or above subtitle text — never rely on color alone; add colon prefix: "ARIA: The door is locked."]
- **Background**: [Semi-transparent black panel, 70% opacity, behind all subtitle text — ensures contrast against any game world background]
- **Font size minimum**: [24px at 1080p reference — scales with text scale setting]
- **Line break behavior**: [Break at natural language pause points — before conjunctions, after commas, never mid-word]
- **Subtitle persistence**: [Each subtitle line holds for the duration of the spoken line plus 300ms after it ends — never disappear while audio is still playing]
- **Non-dialogue captions**: [Document whether ambient sounds, music descriptions, and sound effects are captioned — e.g., "[tense music]", "[explosion in the distance]" — and where these appear if different from dialogue subtitles]
### 10.5 HUD Opacity and Visibility Controls
The following player-adjustable settings must be available from the Accessibility menu:
| Setting | Range | Default | Effect |
|---------|-------|---------|--------|
| [HUD Opacity — Global] | [0% (HUD hidden) to 100%] | [100%] | [Scales all HUD element opacities simultaneously] |
| [HUD Text Scale] | [75% to 150%] | [100%] | [Scales all HUD text elements; layout adapts] |
| [Damage Number Visibility] | [On / Off] | [On] | [Enables or disables all floating damage numbers] |
| [Minimap Visibility] | [On / Off / Compass Only] | [On] | [Compass strip shown as fallback when minimap off] |
| [Notification Verbosity] | [All / Important Only / Off] | [All] | [All = all toasts; Important Only = quest + level up; Off = no toasts] |
| [Motion Reduction] | [On / Off] | [Off] | [When On, replaces all animated HUD transitions with instant state changes] |
| [High Contrast Mode] | [On / Off] | [Off] | [Applies high contrast visual theme to all HUD elements — see art bible for HC variants] |
---
## 11. Tuning Knobs
> **Why this section exists**: HUD behavior should be data-driven to the same degree
> as gameplay systems. Values that are hardcoded are values that require an engineer
> to change. Values that are in config can be tuned by a designer or adjusted for
> player preferences. Document all tunable parameters before implementation so the
> programmer knows which values to externalize.
| Parameter | Current Value | Range | Effect of Increase | Effect of Decrease | Player Adjustable? | Notes |
|-----------|-------------|-------|-------------------|-------------------|-------------------|-------|
| [Notification display duration (default)] | [2000ms] | [500ms – 5000ms] | [Toasts persist longer — less likely to be missed, more screen clutter] | [Toasts disappear faster — cleaner, higher miss risk] | [No — but player can adjust verbosity level] | [Per-type overrides in Section 8 take precedence] |
| [Notification queue max size] | [8] | [3 – 15] | [More messages preserved but queue takes longer to clear] | [Older messages dropped earlier] | [No] | [Expand if playtesting reveals important messages being lost] |
| [Health bar low-HP pulse frequency] | [1 Hz] | [0.5 – 2 Hz] | [More urgent feeling — can become fatiguing] | [Calmer — may fail to communicate urgency] | [No — but Reduced Motion disables it] | [Linked to accessibility setting] |
| [Combat HUD reveal duration] | [0ms (instant)] | [0 – 300ms] | [Softer reveal — feels less jarring] | [Instant — highest responsiveness] | [No] | [Keep at 0ms — combat information must be instant] |
| [Exploration HUD fade-out delay] | [10000ms (10s after last threat)] | [3000 – 30000ms] | [HUD fades sooner — cleaner exploration] | [HUD stays longer — more reassurance] | [No] | [Tune based on playtest; 10s is a starting estimate] |
| [Minimap range (world units visible)] | [80] | [40 – 200] | [More map context visible] | [Tighter local view] | [Yes — Small/Medium/Large preset] | [Exposed as S/M/L, not raw unit value] |
| [Minimap size (px radius at 1080p)] | [75] | [50 – 120] | [Larger map, more screen space consumed] | [Smaller, less intrusive] | [Yes — S/M/L preset] | [Three sizes exposed to player] |
| [Damage number duration (ms)] | [800] | [400 – 1500] | [Numbers linger longer — easier to read, more cluttered] | [Numbers clear faster — cleaner, harder to parse] | [No] | [Tune based on visual noise in dense combat] |
| [Global HUD opacity] | [100%] | [0 – 100%] | [Fully visible] | [Fully hidden] | [Yes — opacity slider in Accessibility settings] | [0% = full HUD off; some players prefer this] |
---
## 12. Acceptance Criteria
> **Why this section exists**: These criteria are the certification checklist for the
> HUD. Every item must pass before the HUD can be marked Approved. QA must be able
> to verify each item independently.
**Layout & Visibility**
- [ ] All HUD elements are within platform safe zone margins on all target platforms
- [ ] No two HUD elements overlap in any documented gameplay context
- [ ] HUD occupies less than [12]% of screen area in exploration context (measure at reference resolution)
- [ ] HUD occupies less than [22]% of screen area in combat context
- [ ] No HUD element occupies the center [40]% of screen during exploration (crosshair excepted during combat)
- [ ] All HUD elements are visible and legible at minimum supported resolution on all platforms
**Per-Context Correctness**
- [ ] HUD correctly shows only specified elements in every context defined in Section 5
- [ ] Context transitions (combat enter/exit, dialogue, cinematic) show correct elements within transition timing spec
- [ ] Boss health bar appears correctly on boss encounter trigger and disappears after boss defeat
- [ ] Death state correctly hides all gameplay HUD elements
**Accessibility**
- [ ] All HUD text elements meet 4.5:1 contrast ratio against all backgrounds they appear over (test light AND dark scenes)
- [ ] No HUD element uses color as the ONLY differentiator (verify: remove color from each element and confirm information is still communicated)
- [ ] Subtitles appear for all voiced lines and ambient dialogue when subtitle setting is enabled
- [ ] Subtitle text never disappears while audio is still playing
- [ ] Reduced Motion setting disables all HUD animations listed in Section 10.3
- [ ] Text Scale 150% does not cause any HUD text to overflow its container or overlap another element
- [ ] All player-adjustable HUD settings in Section 10.5 are functional and persist between sessions
**Notifications**
- [ ] Notifications of the same type that fire within 500ms merge into a single notification
- [ ] Low-priority notifications are queued (not displayed) during combat and released post-combat
- [ ] Critical warnings (low health, hazard) appear immediately regardless of queue state or combat state
- [ ] No more than [3] notification toasts are visible simultaneously
- [ ] Notification queue is cleared correctly on level transition (no stale notifications from previous area)
**Platform**
- [ ] All elements respect 10% safe zone margins on console (test on physical TV — not monitor)
- [ ] HUD displays correctly at 1280x720 (Steam Deck) with no element clipping or overlap
- [ ] HUD elements are repositionable (Health, Minimap, Ability Bar) and reposition settings persist
- [ ] Controller disconnection during play does not cause HUD state corruption
---
## 13. Open Questions
> Track unresolved design questions here. All questions must be resolved before
> the HUD design document can be marked Approved.
| Question | Owner | Deadline | Resolution |
|----------|-------|----------|-----------|
| [e.g., Should the minimap show enemy positions by default, or only after a detection skill is unlocked?] | [systems-designer + ui-designer] | [Sprint 5, Day 2] | [Pending — depends on progression GDD decision] |
| [e.g., Does the game have a boss health bar, or do bosses use the standard enemy health bar? Bosses need a visually distinct treatment if they are significantly more important than normal enemies.] | [game-designer] | [Sprint 5, Day 1] | [Pending] |
| [e.g., Damage numbers: diegetic (floating in world space, occluded by geometry) or screen space (always readable, overlaid on HUD layer)?] | [ui-designer + lead-programmer] | [Sprint 4, Day 5] | [Pending — architecture decision affects rendering layer choice] |
| [e.g., Mobile portrait vs. landscape: does the game support both orientations? If yes, each requires its own zone layout.] | [producer] | [Sprint 3, Day 3] | [Pending — platform scope decision required first] |

1072
.claude/docs/templates/interaction-pattern-library.md vendored Normal file
View file

File diff suppressed because it is too large Load diff

357
.claude/docs/templates/player-journey.md vendored Normal file
View file

@ -0,0 +1,357 @@
# Player Journey Map: [Game Title]
> **Status**: Draft | In Review | Approved
> **Author**: [game-designer / creative-director]
> **Last Updated**: [Date]
> **Links To**: `design/gdd/game-concept.md`, `design/gdd/game-pillars.md`
---
## Journey Overview
[One paragraph capturing the full emotional arc from first launch to long-term
play. This is the player's story, not the game's feature list. Describe the
journey in emotional terms: where do they start (curious, skeptical, cautious),
how does the relationship with the game deepen, what is the peak emotional
experience, and what sustains them afterward?
Example: "The player arrives skeptical and slightly overwhelmed, is quickly
disarmed by an early moment of unexpected delight, spends the middle hours
discovering that the systems run deeper than they first appeared, and eventually
reaches a state of confident mastery where they generate their own challenges and
share their discoveries with others."
If this arc cannot be described in one paragraph, the emotional design is not
yet clear enough — resolve that ambiguity before filling in the phases below.]
---
## Target Player Archetype
[3-4 lines describing the player's MINDSET and gaming literacy, not their
demographics. Demographics answer "who are they" — this answers "how do they
approach games."
Describe: What expectations do they carry from other games? How patient are
they with systems that don't explain themselves? Do they read tooltips or ignore
them? Do they lean into challenge or route around it? Are they here for a story,
a power trip, a creative outlet, or a test of skill?
Example: "A player who has finished at least one other game in this genre and
arrived with a specific hypothesis about what to expect. They are willing to
invest 30+ minutes before judging the game, they read item descriptions, and they
find emergent mastery more satisfying than scripted victories. They feel respected
when the game trusts them to figure things out."]
---
## Journey Phases
> **Guidance**: The six phases below are the standard template. Not all phases
> apply to all games. A short narrative game may not have Habitual Play or
> Long-Term Engagement. A puzzle game may compress Orientation into First Contact.
> Delete or merge phases that genuinely do not apply — do not fill them with
> placeholder values to make the template look complete.
---
### Phase 1: First Contact (0-5 minutes)
**Emotional state on arrival**: [What is the player feeling before they touch
the game? They may be skeptical (purchased on impulse), curious (followed
recommendations), or expectant (been waiting for it). This state is your
starting condition — your design must meet them there.]
**Primary question the player is asking**: [e.g., "Is this worth my time?",
"Will this be too hard?", "Do I understand what I'm supposed to do?"]
**Key experience the game must deliver**:
[What MUST happen in these five minutes for the player to stay? Not a tutorial
beat — an emotional beat. The first contact experience should answer the player's
primary question with a confident "yes." It may be a moment of beauty, a
satisfying mechanical click, a surprising twist on a familiar genre pattern, or
an early win that feels earned.]
**Emotional state on exit**: [What does success look like? e.g., "Curious
about the next layer", "Surprised that this feels different from similar games",
"Already thinking about a decision they made and whether it was right."]
**Risk if this phase fails**: [What does the player do? e.g., "Refund within
the 2-hour Steam window", "Put it down and never return", "Post a negative
first impression", "Recommend it to no one."]
---
### Phase 2: Orientation (5-30 minutes)
**Emotional state on arrival**: [Player is intrigued but not yet committed.
They are forming their first mental model of what this game is.]
**Primary question the player is asking**: [e.g., "How does this actually work?",
"What am I building toward?", "Am I going to be good at this?"]
**Key experience the game must deliver**:
[This is the window where the player builds their foundational mental model.
Describe the one or two "aha" moments that crystallize the game's identity.
The player should feel competence growing — their predictions about the game
should start coming true. They should also catch their first glimpse of depth:
a system or interaction that hints "this goes further than I thought."]
**Emotional state on exit**: [e.g., "Has a working model of the core loop",
"Has made at least one meaningful decision they care about the outcome of",
"Feels the skill ceiling is higher than it first appeared."]
**Risk if this phase fails**: [e.g., "Player concludes the game is shallow",
"Player feels lost and stops trying", "Player never forms a goal."]
---
### Phase 3: First Mastery (30 minutes - 2 hours)
**Emotional state on arrival**: [Player understands the basics and is testing
the edges. They are actively trying to get better rather than just trying to
understand.]
**Primary question the player is asking**: [e.g., "What's the right strategy?",
"What's possible if I get good at this?", "What am I missing?"]
**Key experience the game must deliver**:
[This is the phase where the player earns their first genuine skill victory —
a moment where something that was hard becomes easy through their own growth,
not through the game getting easier. It should feel like crossing a threshold.
They should also discover their first piece of emergent depth: a system
interaction, a build synergy, or a hidden mechanic that rewards curiosity.
According to Csikszentmihalyi's flow model, challenge must scale here — introduce
the first real test of the skills they've been building.]
**Emotional state on exit**: [e.g., "Proud of a specific decision or victory",
"Has an opinion about what the 'right' way to play is (even if wrong)",
"Has questions they want to answer in their next session."]
**Risk if this phase fails**: [e.g., "Player never reaches flow state and stops
before the game gets interesting", "Player forms wrong mental model and blames
the game when it breaks."]
---
### Phase 4: Depth Discovery (2-10 hours)
**Emotional state on arrival**: [Player has a working strategy and is starting
to see its limits. They are ready to discover that there is more.]
**Primary question the player is asking**: [e.g., "Is there a better way?",
"What am I missing that other players know?", "How deep does this actually go?"]
**Key experience the game must deliver**:
[This is where the game's true depth must reveal itself. Players who reach this
phase are your core audience — they have cleared the onboarding and proven their
commitment. They should discover systems, combinations, or strategies that
recontextualize everything they have done so far. The world should feel larger
than the tutorial implied. This is also the phase where Bartle's Explorers find
their reward: content and knowledge that only the curious find.
Design note: Depth Discovery is where many indie games fail silently. Players
exhaust the visible content without ever finding the hidden depth. Audit every
layer of depth in this window and confirm it is discoverable without a guide.]
**Emotional state on exit**: [e.g., "Has rebuilt their strategy from scratch
at least once", "Can imagine multiple viable approaches to the same problem",
"Has discovered at least one thing that surprised them."]
**Risk if this phase fails**: [e.g., "Player concludes they have 'finished'
the game and feels mild disappointment", "Player recommends the game but says
'it's a bit short.'"]
---
### Phase 5: Habitual Play (10-50 hours)
> *Note: Not applicable to short-form games (visual novels, short narrative
> games, puzzle games with fixed content). Delete this phase if the game's
> intended experience concludes before this timeframe.*
**Emotional state on arrival**: [Player considers themselves competent. The
game has become part of their routine. They have a playstyle identity.]
**Primary question the player is asking**: [e.g., "What's my next goal?",
"Can I beat my previous record?", "What haven't I tried yet?"]
**Key experience the game must deliver**:
[Habitual play requires the game to offer goals beyond the tutorial narrative.
The player generates their own challenges, pursues optional content, or begins
competing (against the game, other players, or their own records). This phase
sustains through Bartle's Achiever motivations: collection completion, mastery
benchmarks, visible milestones. It also requires natural session endings that
leave forward tension — the player should always stop with something unfinished
that they want to return to.]
**Emotional state on exit**: [e.g., "Has a specific goal they are working toward
across multiple sessions", "Considers themselves part of a community of people
who play this game."]
**Risk if this phase fails**: [e.g., "Player churns after completing main content
and never returns", "Game fails word-of-mouth because players don't develop
strong opinions about it."]
---
### Phase 6: Long-Term Engagement (50+ hours)
> *Note: Only applies to games designed for extended play — live service games,
> deeply systemic games, competitive games, and games with community-driven
> content. Delete this phase if it does not fit the game's design intent.*
**Emotional state on arrival**: [Player is a veteran. The game is part of their
identity to some degree. They are invested in the community and the ecosystem.]
**Primary question the player is asking**: [e.g., "What's new?", "Can I reach
the top?", "Can I find something no one has found before?"]
**Key experience the game must deliver**:
[Long-term engagement is sustained by different mechanisms than initial fun:
social status, creative expression, competitive standing, or the role of expert
and guide. Design for this phase by asking what role a veteran player wants to
play in the ecosystem — not just what content they want to consume. Systems
that enable knowledge transfer (guides, community sharing, mentorship) dramatically
extend this phase.]
**Emotional state on exit**: [e.g., "Part of a community", "Considered an
expert by newer players", "Invested in the game's ongoing development and direction."]
**Risk if this phase fails**: [e.g., "Veteran players leave and take their
social influence with them, accelerating churn in the broader player base."]
---
## Critical Moments
> **Guidance**: These are specific, individual events — not phases — that
> must land with precision. A critical moment is a single interaction, scene,
> or beat that carries outsized emotional weight. Missing it (through bad UX,
> poor timing, or weak feedback) can derail the entire journey. Identify 8-15
> such moments across the game.
| Moment | Phase | Emotional Target | If It Fails |
|--------|-------|-----------------|-------------|
| [The first death] | [First Contact] | [Surprise followed by understanding — "I see what I did wrong"] | [Player feels the death was unfair and loses trust in the game's fairness] |
| [The first big win] | [Orientation] | [Earned pride — "I figured that out myself"] | [Player feels the win was handed to them and undervalues it] |
| [The first system discovery] | [First Mastery] | [Delight — "I didn't know you could do that"] | [Player misses it entirely and never discovers the depth] |
| [The moment the world opens up] | [Depth Discovery] | [Awe followed by hunger — "How much more is there?"] | [Player feels underwhelmed and concludes they have seen everything] |
| [The first endgame goal] | [Habitual Play] | [Renewed purpose — "Now I have something to work toward"] | [Player completes the main content and feels finished] |
| [Add moment] | [Phase] | [Emotional target] | [Failure consequence] |
---
## Retention Hooks
> **Guidance**: Retention hooks are the specific mechanisms that pull the player
> back to the next session. They operate at different time scales. A game with
> only one hook type has a fragile retention loop. Strong games layer multiple
> hook types, so players with different motivations all have a reason to return.
>
> Map each hook to the systems that deliver it — if a hook has no system behind
> it, it is an aspiration, not a design.
| Hook Type | Hook Description | Systems That Deliver It |
|-----------|-----------------|------------------------|
| **Session Start** | [What draws the player in when they launch? e.g., "Unresolved choices from last session", "World state changed while they were away", "Daily reward waiting"] | [System names, e.g., "Persistent world state, save system, daily login reward"] |
| **Session End** | [What feeling do they have as they close the game? e.g., "A goal just out of reach", "A question unanswered", "An upgrade ready to use next time"] | [e.g., "Progress bar at 90%, next-session unlock notification"] |
| **Daily Return** | [What reason exists to play today vs. skipping a day? e.g., "Daily challenge", "Time-gated resource replenishment", "Limited-time event"] | [e.g., "Daily quest system, resource regen timers, event calendar"] |
| **Long-Term** | [What provides purpose across weeks? e.g., "Season pass milestones", "Competitive ranking reset", "Community challenge goals"] | [e.g., "Ranked system, seasonal content, community events"] |
---
## Player Progression Feel
[Describe HOW the player should experience their progression — not the mechanical
system (that belongs in GDDs), but the FEELING of growing.
Choose the primary progression feeling and describe what it should feel like in
concrete emotional terms. Examples of distinct progression feelings:
- **Power growth**: "The player should feel increasingly dangerous. Early game
combat should feel tense and measured; late game combat should feel effortless
against common enemies, reserving challenge for elite encounters."
- **World expansion**: "The player's sense of the world should grow outward.
Each new area should make the map feel larger, not just longer."
- **Story revelation**: "The player should feel like they are slowly assembling
a picture. Early revelations should recontextualize what they have already seen."
- **Skill improvement**: "The player should feel themselves getting sharper.
Encounters they struggled with early should feel controlled by mid-game,
not because they got more powerful, but because their decisions improved."
- **Community status**: "The player should feel a growing sense of belonging and
recognition within the player community as their knowledge deepens."
Answer: what is the primary progression feeling in this game, and what does it
concretely look and feel like at the beginning, middle, and end of the journey?]
---
## Anti-Patterns to Avoid
> **Guidance**: Anti-patterns are recurring design mistakes that reliably
> break the player journey. List the ones most relevant to this specific game
> and how the design actively guards against them. Be specific — "avoid bad UX"
> is not an anti-pattern, it is a platitude.
- **[Player feels punished for experimenting]**: [e.g., "The crafting system
should never consume irreplaceable resources. All experiment costs must be
recoverable within one session."]
- **[Player loses progress with no explanation]**: [e.g., "All save points are
visible before risky encounters. Progress loss must always be preceded by a
warning the player could have noticed."]
- **[Difficulty spike creates a wall, not a gate]**: [e.g., "When a player
fails an encounter three times, the game surfaces a contextual hint. A wall
stops progress; a gate requires the right key — make sure players know what
key they need."]
- **[Player reaches the content ceiling before the emotional arc completes]**:
[e.g., "The game should never run out of content while the player still has
unanswered questions about the world or their build."]
- **[Mandatory systems are introduced too late to feel meaningful]**: [e.g.,
"Any system the player must engage with in the late game must be introduced
in an optional or low-stakes context earlier."]
- **[Add anti-pattern specific to this game's design risks]**: [Description]
---
## Validation Questions
> **Guidance**: These are questions a playtester session facilitator asks
> during or after a session to verify the journey is working as intended.
> They are not yes/no questions — they probe the player's emotional experience
> and surface gaps between design intent and player reality.
**First Contact (0-5 min)**
- [ ] "Without looking at any menus or tooltips, what do you think this game is about?"
- [ ] "What's the first thing you want to do next?"
**Orientation (5-30 min)**
- [ ] "What does winning or succeeding look like to you right now?"
- [ ] "Is there anything you feel like you should understand but don't?"
**First Mastery (30 min - 2 hrs)**
- [ ] "What's the best decision you've made so far? Why did you make it?"
- [ ] "What would you do differently if you started over?"
**Depth Discovery (2-10 hrs)**
- [ ] "Has the game surprised you? When? How did it feel?"
- [ ] "What questions do you have about systems you haven't fully explored?"
**Habitual Play (10-50 hrs)**
- [ ] "What's your current goal? How long have you been working toward it?"
- [ ] "Have you told anyone about this game? What did you say?"
**General (any phase)**
- [ ] "If you had to stop playing right now, what would you be most eager to
come back for?"
- [ ] "Is there anything you feel the game is not letting you do that you want to do?"
---
## Open Questions
| Question | Owner | Deadline | Resolution |
|----------|-------|----------|-----------|
| [Does the Phase 1 hook work for players without prior genre experience?] | [game-designer] | [Date] | [Unresolved] |
| [Is Phase 4 depth discoverable without external guides?] | [game-designer, ux-designer] | [Date] | [Unresolved] |
| [Add question] | [Owner] | [Date] | [Resolution] |

14
.claude/docs/templates/technical-design-document.md vendored
View file

@ -8,6 +8,20 @@
- **Related ADR**: [ADR-XXXX if applicable]
- **Related Design Doc**: [Link to game design doc this implements]
## Engine API Surface
| Field | Value |
|-------|-------|
| **Engine** | [e.g. Godot 4.6 / Unity 6 / Unreal Engine 5.4] |
| **APIs Depended On** | [Specific classes/methods/nodes used, version-pinned — e.g. `CharacterBody3D.move_and_slide() (Godot 4.x)`] |
| **References Consulted** | [engine-reference docs read before writing this — e.g. `docs/engine-reference/godot/modules/physics.md`] |
| **Post-Cutoff Features Used** | [Features from engine versions beyond LLM training cutoff, or "None"] |
| **Unverified Assumptions** | [API behaviours assumed but not yet tested against the target version, or "None"] |
| **Engine Upgrade Risk** | [LOW / MEDIUM / HIGH — how fragile is this design if the engine version changes?] |
> **Rule**: If any **Unverified Assumptions** are listed, this document cannot be marked
> as Accepted until those assumptions are validated in the actual engine environment.
## Overview
[2-3 sentence summary of what this system does and why it exists]

544
.claude/docs/templates/ux-spec.md vendored Normal file
View file

@ -0,0 +1,544 @@
# UX Specification: [Screen / Flow Name]
> **Status**: Draft | In Review | Approved | Implemented
> **Author**: [Name or agent — e.g., ui-designer]
> **Last Updated**: [Date]
> **Screen / Flow Name**: [Short identifier used in code and tickets — e.g., `InventoryScreen`, `NewGameFlow`]
> **Platform Target**: [PC | Console | Mobile | All — list all that this spec covers]
> **Related GDDs**: [Links to the GDD sections that generated this UI requirement — e.g., `design/gdd/inventory.md § UI Requirements`]
> **Related ADRs**: [Any architectural decisions that constrain this screen — e.g., `ADR-0012: UI Framework Selection`]
> **Related UX Specs**: [Sibling and parent screens — e.g., `ux-spec-pause-menu.md`, `ux-spec-settings.md`]
> **Accessibility Tier**: Basic | Standard | Comprehensive | Exemplary
> **Note — Scope boundary**: This template covers discrete screens and flows (menus,
> dialogs, inventory, settings, cutscene UI, etc.). For persistent in-game overlays
> that exist during active gameplay, use `hud-design.md` instead. If a screen is a
> hybrid (e.g., a pause menu that overlays the game world), treat it as a screen spec
> and note the overlay relationship in Navigation Position.
---
## 1. Purpose & Player Need
> **Why this section exists**: Every screen must justify its existence from the
> player's perspective. Screens that are designed from a developer perspective ("display
> the save data") produce cluttered, confusing interfaces. Screens designed from the
> player's perspective ("let the player feel confident their progress is safe before they
> put the controller down") produce purposeful, calm interfaces. Write this section before
> touching any layout decisions — it is the filter through which every subsequent choice
> is evaluated.
**What player need does this screen serve?**
[One paragraph. Name the real human need, not the system function. Consider: what would
a player say they want when they open this screen? What would frustrate them if it did
not work? That frustration describes the need.
Example — bad: "Displays the player's current items and equipment."
Example — good: "Lets the player understand what they're carrying and quickly decide what
to take into the next encounter, without breaking their mental model of the game world.
The inventory is the player's planning tool between moments of action."]
**The player goal** (what the player wants to accomplish):
[One sentence. Specific enough that you could write an acceptance criterion for it.
Example: "Find the item they are looking for within three button presses and equip it
without navigating to a separate screen."]
**The game goal** (what the game needs to communicate or capture):
[One sentence. This is what the system needs from this interaction. Example: "Record the
player's equipment choices and relay them to the combat system before the next encounter
loads." This section prevents UI that looks good but fails to serve the system it is
part of.]
---
## 2. Player Context on Arrival
> **Why this section exists**: Screens do not exist in isolation. A player opening the
> inventory mid-combat is in a completely different cognitive and emotional state than
> a player opening it after clearing a dungeon. The same information architecture can
> feel oppressively complex in one context and trivially simple in another. Document the
> context so that design decisions — what to show first, what to hide, what to animate,
> what to simplify — are calibrated to the actual player arriving at this screen, not
> an abstract user.
| Question | Answer |
|----------|--------|
| What was the player just doing? | [e.g., Completed a combat encounter / Pressed Esc from exploration / Triggered a story cutscene] |
| What is their emotional state? | [e.g., High tension — just narrowly survived / Calm — exploring between objectives] |
| What cognitive load are they carrying? | [e.g., High — actively tracking enemy positions / Low — no active threats] |
| What information do they already have? | [e.g., They know they just picked up an item but haven't seen its stats yet] |
| What are they most likely trying to do? | [e.g., Check if the new item is better than their current weapon — primary use case] |
| What are they likely afraid of? | [e.g., Missing something, making an irreversible mistake, losing track of where they were] |
**Emotional design target for this screen**:
[One sentence describing the feeling the player should have while using this screen.
Example: "Confident and in control — the player should feel like they have complete
information and complete authority over their choices, with no ambiguity about outcomes."]
---
## 3. Navigation Position
> **Why this section exists**: A screen that does not know where it sits in the
> navigation hierarchy cannot define its entry/exit transitions, its back-button
> behavior, or its relationship to the game's pause state. Navigation position also
> reveals architectural problems early — if this screen is reachable from eight
> different places, that is a complexity flag that should be resolved in design, not
> implementation.
**Screen hierarchy** (use indentation to show parent-child relationships):
```
[Root — e.g., Main Menu]
└── [Parent Screen — e.g., Settings]
└── [This Screen — e.g., Audio Settings]
├── [Child Screen — e.g., Advanced Audio Options]
└── [Child Screen — e.g., Speaker Test Dialog]
```
**Modal behavior**: [Modal (blocks everything behind it, requires explicit dismiss) | Non-modal (game continues behind it) | Overlay (renders over game world, game paused) | Overlay-live (renders over game world, game continues)]
> If this screen is modal: document the dismiss behavior. Can it be dismissed by pressing
> Back/B? By pressing Escape? By clicking outside it? Can it be dismissed at all, or
> must the player complete it? Undismissable modals are high-friction — justify them.
**Reachability — all entry points**:
| Entry Point | Triggered By | Notes |
|-------------|-------------|-------|
| [e.g., Main Menu → Play] | [Player selects "New Game"] | [Primary entry point] |
| [e.g., Pause Menu → Resume] | [Player presses Start from any gameplay state] | [Secondary entry] |
| [e.g., Game event] | [Tutorial system forces open first time only] | [Systemic entry — must not break if player dismisses] |
---
## 4. Entry & Exit Points
> **Why this section exists**: Entry and exit define the screen's contract with the
> rest of the navigation system. Every entry point must have a corresponding exit point.
> Transitions that are undefined become bugs — the player finds themselves stuck, or the
> game state becomes inconsistent. Fill this table completely before implementation
> begins. Empty cells are a sign that design work is unfinished.
**Entry table**:
| Trigger | Source Screen / State | Transition Type | Data Passed In | Notes |
|---------|----------------------|-----------------|----------------|-------|
| [e.g., Player presses Inventory button] | [Gameplay / Exploration state] | [Overlay push — game pauses] | [Current player loadout, inventory contents] | [Works from any non-combat state] |
| [e.g., Item pickup prompt accepted] | [Gameplay / Item Pickup dialog] | [Replace dialog with full inventory] | [Newly acquired item pre-highlighted] | [The new item should be visually distinguished on open] |
| [e.g., Quest system directs player to inventory] | [Gameplay / Quest Update notification] | [Overlay push] | [Quest-relevant item ID for highlight] | [Screen should deep-link to the relevant item] |
**Exit table**:
| Exit Action | Destination | Transition Type | Data Returned / Saved | Notes |
|-------------|------------|-----------------|----------------------|-------|
| [e.g., Player closes inventory (Back/B/Esc)] | [Previous state — Exploration] | [Overlay pop — game resumes] | [Updated equipment loadout committed] | [Changes must be committed before transition begins] |
| [e.g., Player selects "Equip" on item] | [Same screen, updated state] | [In-place state change] | [Loadout change event fired] | [No navigation, just a state refresh] |
| [e.g., Player navigates to Map from inventory shortcut] | [Map Screen] | [Replace] | [No data] | [Inventory state is preserved if player returns] |
---
## 5. Layout Specification
> **Why this section exists**: The layout specification is the handoff artifact between
> UX design and UI programming. It does not need to be pixel-perfect — it needs to
> communicate hierarchy (what is important), proximity (what belongs together), and
> proportion (what is big vs. small). ASCII wireframes achieve this without requiring
> design software. A programmer who reads this section should be able to build the
> correct structure without guessing. An artist who reads it should know where
> visual weight should be concentrated.
>
> Draw the layout at one standard resolution (e.g., 1920x1080). Note adaptations
> for other resolutions separately.
### 5.1 Wireframe
```
[Draw the screen layout using ASCII art. Suggested characters:
┌ ┐ └ ┘ │ ─ for borders
╔ ╗ ╚ ╝ ║ ═ for emphasized/modal borders
[ ] for interactive elements (buttons, inputs)
{ } for content areas (lists, grids, images)
... for scrollable content
● for the focused element on open
Example:
┌──────────────────────────────────────────────┐
│ [← Back] INVENTORY [Options] │ ← HEADER ZONE
├──────────────────────────────────────────────┤
│ ┌──────────────┐ ┌─────────────────────────┐│
│ │ CATEGORY NAV │ │ ITEM DETAIL PANEL ││ ← CONTENT ZONE
│ │ ● Weapons │ │ Item Name ││
│ │ Armor │ │ {item icon} ││
│ │ Consumable│ │ Stats comparison ││
│ │ Key Items │ │ Description text... ││
│ ├──────────────┤ └─────────────────────────┘│
│ │ ITEM GRID │ │
│ │ {□}{□}{□}{□} │ │
│ │ {□}{□}{□}{□} │ │
│ │ ... │ │
│ └──────────────┘ │
├──────────────────────────────────────────────┤
│ [Equip] [Drop] [Compare] [Close] │ ← ACTION BAR
└──────────────────────────────────────────────┘
]
```
### 5.2 Zone Definitions
| Zone Name | Description | Approximate Size | Scrollable? | Overflow Behavior |
|-----------|-------------|-----------------|-------------|-------------------|
| [e.g., Header Zone] | [Top bar: navigation, screen title, global actions] | [Full width, ~10% height] | [No] | [Truncate long screen names with ellipsis] |
| [e.g., Category Nav] | [Left panel: item category tabs] | [~25% width, ~75% height] | [Yes — vertical if categories exceed panel] | [Scroll indicator appears at bottom of list] |
| [e.g., Item Grid] | [Center: grid of item icons for selected category] | [~45% width, ~75% height] | [Yes — vertical] | [Page-based: 4x4 grid, next page on overflow] |
| [e.g., Detail Panel] | [Right: stats and description for selected item] | [~30% width, ~75% height] | [Yes — vertical for long descriptions] | [Fade at bottom, scroll to reveal] |
| [e.g., Action Bar] | [Bottom: context-sensitive actions for selected item] | [Full width, ~15% height] | [No] | [Actions collapse to icon-only below 4] |
### 5.3 Component Inventory
> List every discrete UI component on this screen. This table drives the implementation
> task list — each row becomes a component to build or reuse.
| Component Name | Type | Zone | Purpose | Required? | Reuses Existing Component? |
|----------------|------|------|---------|-----------|---------------------------|
| [e.g., Back Button] | [Button] | [Header] | [Returns to previous screen] | [Yes] | [Yes — standard NavButton component] |
| [e.g., Screen Title Label] | [Text] | [Header] | [Displays "INVENTORY" or context name] | [Yes] | [Yes — ScreenTitle component] |
| [e.g., Category Tab] | [Toggle Button] | [Category Nav] | [Filters item grid by category] | [Yes] | [No — new component needed] |
| [e.g., Item Slot] | [Icon + Frame] | [Item Grid] | [Represents one inventory slot, empty or filled] | [Yes] | [No — new component] |
| [e.g., Item Name Label] | [Text] | [Detail Panel] | [Shows selected item's name] | [Yes] | [Yes — BodyText component] |
| [e.g., Stat Comparison Row] | [Compound — label + value + delta] | [Detail Panel] | [Shows stat value vs. currently equipped] | [Yes] | [No — new component] |
| [e.g., Equip Button] | [Primary Button] | [Action Bar] | [Equips selected item in appropriate slot] | [Yes] | [Yes — PrimaryAction component] |
| [e.g., Empty State Message] | [Text + Icon] | [Item Grid] | [Shown when category has no items] | [Yes] | [Yes — EmptyState component] |
**Primary focus element on open**: [e.g., The first item in the Item Grid — or, if deep-linked, the highlighted item. If the grid is empty, focus lands on the first Category Tab.]
---
## 6. States & Variants
> **Why this section exists**: A screen is not a single picture — it is a set of
> states, each of which must look correct and behave correctly. Screens that are
> designed only in their "happy path" state ship with broken empty states, invisible
> loading indicators, and crashes when data is missing. Document every state before
> implementation. The states table is also the test matrix for QA.
| State Name | Trigger | What Changes Visually | What Changes Behaviorally | Notes |
|------------|---------|----------------------|--------------------------|-------|
| [Loading] | [Screen is opening, data not yet available] | [Item Grid shows skeleton/shimmer placeholders; Action Bar buttons disabled] | [No interactions possible except Close] | [Should not be visible >500ms under normal conditions; if it is, investigate data fetch performance] |
| [Empty — no items in category] | [Player switches to a category with zero items] | [Item Grid replaced by EmptyState component: icon + "Nothing here yet."] | [Action Bar shows no item actions; Drop/Equip/Compare all hidden] | [Do not show disabled buttons — remove them. Disabled buttons with no tooltip are confusing.] |
| [Populated — items present] | [Category has at least one item] | [Item Grid fills with item slots; first slot is auto-focused] | [All item actions available for selected item] | [Default and most common state] |
| [Item Selected] | [Player navigates to an item slot] | [Detail Panel populates; selected slot has focus ring; Action Bar updates to item's valid actions] | [Equip/Drop/Compare enabled based on item type] | [Equip is disabled if item is already equipped — show a "Equipped" badge instead] |
| [Confirmation Pending — Drop] | [Player selects Drop action] | [Confirmation dialog overlays the screen] | [All background interactions suspended until dialog resolves] | [Use a modal confirmation, not an inline toggle. Items cannot be recovered after dropping.] |
| [Error — data load failed] | [Inventory data could not be retrieved] | [Item Grid shows error state: icon + "Couldn't load items." + Retry button] | [Only Retry and Close are available] | [Log the error; do not expose technical details to player] |
| [Item Newly Acquired] | [Screen opened from item pickup deep-link] | [Newly acquired item has a visual "New" badge; Detail Panel pre-populated with that item] | [Same as Item Selected but with badge until player navigates away] | [Badge persists until the player manually navigates off that slot once] |
---
## 7. Interaction Map
> **Why this section exists**: This section is the source of truth for what every
> input does on this screen. It forces the designer to think through every input
> method (mouse, keyboard, gamepad, touch) and every interactive state (hover, focus,
> pressed, disabled). Gaps in this table are bugs waiting to happen. The
> interaction map is also the input for the accessibility audit — if an action is
> only reachable by mouse, it will fail the keyboard and gamepad columns.
### 7.1 Navigation Inputs
| Input | Platform | Action | Visual Response | Audio Cue | Notes |
|-------|----------|--------|-----------------|-----------|-------|
| [Arrow keys / D-Pad] | [All] | [Move focus within active zone] | [Focus ring moves to adjacent element] | [Soft navigation tick] | [Wrap at edges within zone; do not cross zones with arrows alone] |
| [Tab / R1] | [KB / Gamepad] | [Move focus to next zone (Category → Grid → Detail → Action Bar)] | [Focus ring jumps to first element in next zone] | [Distinct zone-change tone] | [Shift+Tab / L1 goes backward] |
| [Mouse hover] | [PC] | [Show hover state on interactive elements] | [Highlight / underline / color shift] | [None] | [Hover does NOT move focus — only click does] |
| [Mouse click] | [PC] | [Select and focus the clicked element] | [Pressed state flash, then selected/focused] | [Soft click] | [Right-click opens context menu if applicable; otherwise no-op] |
| [Touch tap] | [Mobile] | [Select and activate in one gesture] | [Press ripple] | [Soft click] | [Treat tap as click + confirm for low-risk actions; require explicit confirm for destructive actions] |
### 7.2 Action Inputs
| Input | Platform | Context (What must be focused) | Action | Response | Animation | Audio Cue | Notes |
|-------|----------|-------------------------------|--------|----------|-----------|-----------|-------|
| [Enter / A button / Left click] | [All] | [Item slot focused] | [Select item → populate Detail Panel] | [Detail panel slides in or updates in place] | [Panel fade/slide in, 120ms] | [Soft select tone] | [If item already selected: no-op] |
| [Enter / A button] | [All] | [Equip button focused] | [Equip selected item] | [Button animates press; item badge updates to "Equipped"; previously equipped item loses badge] | [Badge swap, 80ms] | [Equip success sound] | [Fires EquipItem event to Inventory system] |
| [Triangle / Y button / Right-click] | [All] | [Item slot focused] | [Open item context menu] | [Context menu appears adjacent to item slot] | [Popover, 80ms] | [Menu open sound] | [Context menu contains: Equip, Drop, Inspect, Compare] |
| [Square / X button] | [Gamepad] | [Item slot focused] | [Quick-equip without opening detail] | [Equip animation plays inline on slot] | [Slot flash, 80ms] | [Equip success sound] | [Convenience shortcut; does not change screen state] |
| [Esc / B button / Back] | [All] | [Any, screen level] | [Close screen and return to previous state] | [Screen exit transition plays] | [Slide out, 200ms] | [Back/close tone] | [Commits all changes before closing. No discard — inventory is not a draft.] |
| [F / L2] | [KB / Gamepad] | [Any] | [Toggle filter panel] | [Sort/filter overlay opens] | [Slide in from right, 200ms] | [Panel open tone] | [If no items in category, filter is disabled] |
### 7.3 State-Specific Behaviors
| State | Input Restriction | Reason |
|-------|------------------|--------|
| [Loading] | [All item and action inputs disabled] | [No data to act on; prevent race conditions] |
| [Confirmation dialog open] | [Only Confirm and Cancel inputs active] | [Modal — background is locked] |
| [Error state] | [Only Retry and Close active] | [No data available to navigate] |
---
## 8. Data Requirements
> **Why this section exists**: The separation between UI and game state is the most
> important architectural boundary in a game's UI system. UI reads data; it does not
> own it. UI fires events; it does not write state directly. This section defines
> exactly what data this screen needs to display, where it comes from, and how
> frequently it updates. Filling this table before implementation prevents two
> common failure modes: (1) UI developers reaching into systems they should not touch,
> and (2) systems not knowing they need to expose data until a UI is half-built.
| Data Element | Source System | Update Frequency | Who Owns It | Format | Null / Missing Handling |
|--------------|--------------|-----------------|-------------|--------|------------------------|
| [e.g., Item list] | [Inventory System] | [On screen open; on InventoryChanged event] | [InventorySystem] | [Array of ItemData structs: id, name, icon_path, category, stats, is_equipped] | [Empty array → show Empty State. Never null — system must return array.] |
| [e.g., Equipped loadout] | [Equipment System] | [On screen open; on EquipmentChanged event] | [EquipmentSystem] | [Dict mapping slot_id → item_id] | [Unequipped slot has null value — UI shows empty slot icon] |
| [e.g., Item stat comparisons] | [Stats System] | [On item selection change] | [StatsSystem] | [Dict mapping stat_name → {current, new, delta}] | [If no item selected, detail panel shows placeholder. Stats system must handle this gracefully.] |
| [e.g., Player currency] | [Economy System] | [On screen open only — inventory does not show live currency] | [EconomySystem] | [Int — gold pieces] | [If currency system not active for this game mode, hide the currency row entirely] |
| [e.g., Newly acquired item flag] | [Inventory System] | [On screen open] | [InventorySystem] | [Array of item_ids flagged as new] | [If empty array, no badges shown] |
> **Rule**: This screen must never write directly to any system listed above. All
> player actions fire events (see Section 9). Systems update their own data and
> notify the UI.
---
## 9. Events Fired
> **Why this section exists**: This is the other half of the UI/system boundary.
> Where Section 8 defines what the UI reads, this section defines what the UI
> communicates back to the game. Specifying events at design time prevents UI
> programmers from writing game logic, and prevents game programmers from being
> surprised by what the UI does. Every destructive or state-changing player action
> must appear in this table.
| Player Action | Event Fired | Payload | Receiver System | Notes |
|---------------|-------------|---------|-----------------|-------|
| [Player equips an item] | [EquipItemRequested] | [{item_id: string, target_slot: string}] | [Equipment System] | [Equipment System validates the action and fires EquipmentChanged if successful; UI listens for EquipmentChanged to update its display] |
| [Player drops an item] | [DropItemRequested] | [{item_id: string, quantity: int}] | [Inventory System] | [Fires only after player confirms the drop dialog. Inventory System removes the item and fires InventoryChanged.] |
| [Player opens item compare] | [ItemCompareOpened] | [{item_a_id: string, item_b_id: string}] | [Analytics System] | [No game-state change — analytics event only. Compare view is purely local UI state.] |
| [Player closes screen] | [InventoryScreenClosed] | [{session_duration_ms: int}] | [Analytics System] | [Fires on every close regardless of reason. Used for engagement metrics.] |
| [Player navigates between categories] | [InventoryCategoryChanged] | [{category: string}] | [Analytics System] | [Analytics only. No game state change.] |
---
## 10. Transition & Animation
> **Why this section exists**: Transitions are not decoration — they communicate
> hierarchy and causality. A screen that slides in from the right implies the
> player has moved forward. A screen that fades implies a context break. Inconsistent
> transitions make navigation feel broken even when it is technically correct.
> This section ensures transitions are specified intentionally, not left to the
> developer's discretion, and that accessibility settings (reduced motion) are
> planned for from the start.
| Transition | Trigger | Direction / Type | Duration (ms) | Easing | Interruptible? | Skipped by Reduced Motion? |
|------------|---------|-----------------|--------------|--------|----------------|---------------------------|
| [Screen enter] | [Screen pushed onto stack] | [Slide in from right] | [250] | [Ease out cubic] | [No — must complete before interaction is enabled] | [Yes — instant appear at 0ms] |
| [Screen exit — Back] | [Player presses Back] | [Slide out to right] | [200] | [Ease in cubic] | [No] | [Yes — instant disappear] |
| [Screen exit — Forward] | [Player navigates to child screen] | [Slide out to left] | [200] | [Ease in cubic] | [No] | [Yes — instant] |
| [Detail panel update] | [Player selects a new item] | [Cross-fade content] | [120] | [Linear] | [Yes — if player navigates quickly, previous animation cancels] | [Yes — instant swap] |
| [Loading → Populated] | [Data arrives after load] | [Skeleton shimmer fades out, content fades in] | [180] | [Ease out] | [No] | [Yes — instant reveal] |
| [Action Bar button press] | [Player activates a button] | [Scale down 95% on press, return on release] | [60 down / 60 up] | [Ease out / ease in] | [Yes — if released early, returns to normal] | [No — this is tactile feedback, not decorative motion] |
| [Confirmation dialog open] | [Player initiates destructive action] | [Background dims 60% opacity; dialog scales up from 95%] | [150] | [Ease out] | [No] | [Yes — instant appear, no scale] |
| [New item badge appear] | [Screen opens with newly acquired item] | [Badge pops from 0% to 110% to 100% scale] | [200 total] | [Ease out back] | [No] | [Yes — instant appear at 100% scale] |
---
## 11. Input Method Completeness Checklist
> **Why this section exists**: Input completeness is not optional — it is a
> certification requirement for console platforms and a legal risk area for
> accessibility laws in multiple markets. Fill this checklist before marking
> the spec as Approved. Any unchecked item blocks implementation start.
**Keyboard**
- [ ] All interactive elements are reachable using Tab and arrow keys alone
- [ ] Tab order follows visual reading order (left-to-right, top-to-bottom within each zone)
- [ ] Every action achievable by mouse is also achievable by keyboard
- [ ] Focus is visible at all times (no element where focus ring disappears)
- [ ] Focus does not escape the screen while it is open (focus trap for modals)
- [ ] Esc key closes or cancels (and does not quit the game from within a screen)
**Gamepad**
- [ ] All interactive elements reachable with D-Pad and left stick
- [ ] Face button mapping documented and consistent with platform conventions (see Section 7.2)
- [ ] No action requires analog stick precision that cannot be replicated with D-Pad
- [ ] Trigger and bumper shortcuts documented if used
- [ ] Controller disconnection while screen is open is handled gracefully
**Mouse**
- [ ] Hover states defined for all interactive elements
- [ ] Clickable hit targets are at minimum 32x32px (44x44px preferred)
- [ ] Right-click behavior defined (context menu or no-op — not undefined)
- [ ] Scroll wheel behavior defined in all scrollable zones
**Touch (if applicable)**
- [ ] All touch targets are minimum 44x44px
- [ ] Swipe gestures do not conflict with system-level swipe navigation
- [ ] All actions achievable with one hand in portrait orientation
- [ ] Long-press behavior defined if used
---
## 12. Screen-Level Accessibility Requirements
> **Why this section exists**: Accessibility requirements must be specified at design
> time because retrofitting them is expensive and often architecturally impractical.
> This section documents requirements specific to this screen. Project-wide standards
> live in `docs/accessibility-requirements.md` — consult it before filling this
> section so you do not duplicate or contradict project-level commitments.
>
> Accessibility Tiers in this project:
> - Basic: WCAG 2.1 AA text contrast, keyboard navigable, no motion-only information
> - Standard: Basic + screen reader support, colorblind-safe, focus management
> - Comprehensive: Standard + reduced motion support, text scaling, high contrast mode
> - Exemplary: Comprehensive + cognitive load management, AAA equivalent, certified
**Text contrast requirements for this screen**:
| Text Element | Background Context | Required Ratio | Current Ratio | Pass? |
|--------------|-------------------|---------------|---------------|-------|
| [e.g., Item name in Detail Panel] | [Dark panel background ~#1a1a1a] | [4.5:1 (WCAG AA normal text)] | [TBD — verify in implementation] | [ ] |
| [e.g., Category tab label — inactive] | [Mid-grey tab background] | [4.5:1] | [TBD] | [ ] |
| [e.g., Category tab label — active] | [Accent color background] | [4.5:1] | [TBD] | [ ] |
| [e.g., Action button label] | [Button color (varies by state)] | [4.5:1] | [TBD] | [ ] |
| [e.g., Stat comparison delta (positive)] | [Detail panel] | [4.5:1 — do NOT rely on green color alone] | [TBD] | [ ] |
**Colorblind-unsafe elements and mitigations**:
| Element | Colorblind Risk | Mitigation |
|---------|----------------|------------|
| [e.g., Stat delta indicators (red/green for worse/better)] | [Red-green colorblindness (Deuteranopia) — most common form] | [Add arrow icons (↑ / ↓) and +/- prefix in addition to color. Color is a redundant, not sole, indicator.] |
| [e.g., Item rarity color coding (grey/green/blue/purple/orange)] | [Multiple types — rarity color is a common industry failure] | [Add rarity name text label below icon. Color is supplemental only.] |
**Focus order** (Tab key sequence, numbered):
[e.g.,
1. Back button (Header)
2. Options button (Header)
3. Category Tab 1 — Weapons
4. Category Tab 2 — Armor
5. Category Tab 3 — Consumables
6. Category Tab 4 — Key Items
7. Item Slot [0,0]
8. Item Slot [0,1] ... (grid traverses left-to-right, top-to-bottom)
9. Last item slot
10. Equip button (Action Bar)
11. Drop button (Action Bar)
12. Compare button (Action Bar)
13. Close button (Action Bar)
→ Cycles back to Back button
Focus does not enter the Detail Panel — it is a display panel driven by item focus, not independently navigable.]
**Screen reader announcements for key state changes**:
| State Change | Announcement Text | Announcement Timing |
|--------------|------------------|---------------------|
| [Screen opens] | ["Inventory screen. [N] items. [Active category] selected."] | [On screen focus settle] |
| [Player focuses an item slot] | ["[Item name]. [Category]. [Rarity]. [Key stats summary]. [Equipped / Not equipped]."] | [On focus arrival] |
| [Player equips an item] | ["[Item name] equipped to [slot name]."] | [After EquipmentChanged event confirmed] |
| [Player drops an item] | ["[Item name] dropped."] | [After InventoryChanged event confirmed] |
| [Category changes] | ["[Category name]. [N] items."] | [On category tab focus] |
| [Empty state shown] | ["No items in [category name]."] | [When empty state renders] |
**Cognitive load assessment**:
[Estimate the number of information streams the player is simultaneously tracking while
using this screen. For this screen: (1) item grid position, (2) item detail stats,
(3) current equipment loadout for comparison, (4) available actions, (5) item category.
That is 5 concurrent streams — within the standard 7±2 limit, but at the higher end.
Mitigation: detail panel auto-updates on navigation so the player never needs to
manually retrieve item info. Reduce active decisions by surfacing stat comparison
automatically.]
---
## 13. Localization Considerations
> **Why this section exists**: UI built without localization in mind breaks on first
> translation. German text is typically 30–40% longer than English. Arabic and Hebrew
> require right-to-left layout mirroring. Japanese and Chinese text may be significantly
> shorter than English, creating awkward whitespace. These issues are cheap to plan for
> and expensive to fix after a layout is built and shipped. Every text element should
> have an explicit max-character count and a plan for overflow.
**General rules for this screen**:
- All text elements must tolerate a minimum of 40% expansion from English baseline
- RTL layout (Arabic, Hebrew): mirrored layout required — document which elements mirror and which do not
- CJK languages (Japanese, Korean, Chinese): text may be 20-30% shorter — verify layouts do not look broken with less text
- Do not use text in images — all text must be from localization strings
| Text Element | English Baseline Length | Max Characters | Expansion Budget | RTL Behavior | Overflow Behavior | Risk |
|--------------|------------------------|----------------|-----------------|--------------|-------------------|------|
| [e.g., Screen title "INVENTORY"] | [9 chars] | [16 chars] | [78%] | [Mirror to right, or center — acceptable] | [Truncate with ellipsis — title is not critical content] | [Low] |
| [e.g., Item name] | [~15 chars avg, max ~35 "Enchanted Dragon Scale Gauntlets"] | [50 chars] | [43%] | [Right-align in RTL layouts] | [Truncate with tooltip showing full name on hover/focus] | [Medium — long fantasy item names are common] |
| [e.g., Item description] | [~80–120 chars] | [200 chars] | [67%] | [Right-align, wrap normally] | [Scroll within Detail Panel — no truncation] | [Low — panel is scrollable] |
| [e.g., Action button "Equip"] | [5 chars] | [14 chars] | [180%] | [Button layout mirrors; text right-aligns] | [Shrink font to 90% minimum, then truncate] | [Medium — "Ausrüsten" in German is 9 chars] |
| [e.g., Category tab "Consumables"] | [11 chars] | [18 chars] | [64%] | [Mirror tab position] | [Abbreviate: "Consum." — define abbreviations per language in loc file] | [High — long localized tab labels are a known problem] |
---
## 14. Acceptance Criteria
> **Why this section exists**: Acceptance criteria are the contractual definition of
> "done." Without them, implementation is complete when the developer says it is.
> With them, implementation is complete when a QA tester can verify every item on
> this list. Write criteria that a tester can verify independently, without asking the
> designer what they meant. Every criterion should be binary — pass or fail, not
> subjective.
**Performance**
- [ ] Screen opens (first frame visible) within 200ms of trigger on minimum-spec hardware
- [ ] Screen is fully interactive (all data loaded) within 500ms of trigger on minimum-spec hardware
- [ ] Navigation between items produces no perceptible frame drop (maintain target framerate ±5fps)
**Layout & Rendering**
- [ ] Screen displays correctly (no overlap, no cutoff, no overflow) at minimum supported resolution [specify]
- [ ] Screen displays correctly at maximum supported resolution [specify]
- [ ] Screen displays correctly at 4:3, 16:9, 16:10, and 21:9 aspect ratios if targeting PC
- [ ] No text overflow or truncation in English within defined max-character bounds
- [ ] No text overflow or truncation in the longest-translation language [specify — typically German]
- [ ] All states (Loading, Empty, Populated, Error, Confirmation) render correctly
- [ ] Item grid scrolls smoothly without frame drops when all item slots are populated
**Input**
- [ ] All interactive elements reachable by keyboard using Tab and arrow keys only
- [ ] All interactive elements reachable by gamepad using D-Pad and face buttons only
- [ ] All interactive elements reachable by mouse without keyboard
- [ ] No action requires simultaneous input that is not documented in Section 7
- [ ] Focus is visible at all times on keyboard and gamepad navigation
- [ ] Focus does not escape the screen while it is open
**Events & Data**
- [ ] All events in Section 9 fire with correct payloads on all exit paths (verify with debug logging)
- [ ] Screen does not write directly to any game system (verify: no direct state mutation calls)
- [ ] Inventory changes persist correctly after screen is closed and reopened
- [ ] Screen handles InventoryChanged events fired by other systems while it is open without crashing
**Accessibility**
- [ ] All text passes minimum contrast ratios specified in Section 12
- [ ] Stat comparison does not rely on color alone as the sole differentiator
- [ ] Screen reader announces item name and key stats on focus (verify with platform screen reader)
- [ ] Reduced motion setting results in instant transitions (no animated transitions)
- [ ] High contrast mode (if applicable to Accessibility Tier) renders without visual breakage
**Localization**
- [ ] No text element overflows its container in any supported language
- [ ] RTL layout renders correctly (if RTL is a target language)
- [ ] All text elements are driven by localization strings — no hardcoded display text
---
## 15. Open Questions
> Track unresolved design questions here. Each question should have a clear owner
> and a deadline. An Approved spec must have zero open questions — move to a decision
> or explicitly document the deferral rationale.
| Question | Owner | Deadline | Resolution |
|----------|-------|----------|-----------|
| [e.g., Should item comparison be automatic (always showing equipped stats) or player-triggered (press Compare)?] | [ui-designer] | [Sprint 4, Day 3] | [Pending] |
| [e.g., Do we support controller cursor (free aim) in the item grid, or d-pad-only grid navigation?] | [lead-programmer + ui-designer] | [Sprint 4, Day 3] | [Pending — depends on ADR-0015 input model decision] |
| [e.g., What is the game's item drop policy — permanent loss or drop-to-world?] | [systems-designer] | [Requires GDD update] | [Blocked on inventory GDD Edge Cases section] |
| [e.g., Maximum inventory size — does the grid have a hard cap or is it infinite-scroll?] | [economy-designer] | [Sprint 3, Day 5] | [Pending] |

114
.claude/skills/architecture-decision/SKILL.md
View file

@ -8,15 +8,97 @@ allowed-tools: Read, Glob, Grep, Write
When this skill is invoked:
1. **Determine the next ADR number** by scanning `docs/architecture/` for
existing ADRs.
## 0. Load Engine Context (ALWAYS FIRST)
2. **Gather context** by reading related code and existing ADRs.
Before doing anything else, establish the engine environment:
3. **Guide the user through the decision** by asking clarifying questions if
the title alone is not sufficient.
1. Read `docs/engine-reference/[engine]/VERSION.md` to get:
- Engine name and version
- LLM knowledge cutoff date
- Post-cutoff version risk levels (LOW / MEDIUM / HIGH)
4. **Generate the ADR** following this format:
2. Identify the **domain** of this architecture decision from the title or
user description. Common domains: Physics, Rendering, UI, Audio, Navigation,
Animation, Networking, Core, Input, Scripting.
3. Read the corresponding module reference if it exists:
`docs/engine-reference/[engine]/modules/[domain].md`
4. Read `docs/engine-reference/[engine]/breaking-changes.md` — flag any
changes in the relevant domain that post-date the LLM's training cutoff.
5. Read `docs/engine-reference/[engine]/deprecated-apis.md` — flag any APIs
in the relevant domain that should not be used.
6. **Display a knowledge gap warning** before proceeding if the domain carries
MEDIUM or HIGH risk:
```
⚠️ ENGINE KNOWLEDGE GAP WARNING
Engine: [name + version]
Domain: [domain]
Risk Level: HIGH — This version is post-LLM-cutoff.
Key changes verified from engine-reference docs:
- [Change 1 relevant to this domain]
- [Change 2]
This ADR will be cross-referenced against the engine reference library.
Proceed with verified information only — do NOT rely solely on training data.
```
If no engine has been configured yet, prompt: "No engine is configured.
Run `/setup-engine` first, or tell me which engine you are using."
---
## 1. Determine the next ADR number
Scan `docs/architecture/` for existing ADRs to find the next number.
---
## 2. Gather context
Read related code, existing ADRs, and relevant GDDs from `design/gdd/`.
---
## 3. Guide the decision collaboratively
Ask clarifying questions if the title alone is not sufficient. For each major
section, present 2-4 options with pros/cons before drafting. Do not generate
the ADR until the key decision is confirmed by the user.
Key questions to ask:
- What problem are we solving? What breaks if we don't decide this now?
- What constraints apply (engine version, platform, performance budget)?
- What alternatives have you already considered?
- Which post-cutoff engine features (if any) does this decision depend on?
- **Which GDD systems motivated this decision?** For each, what specific
requirement (rule, formula, performance constraint, integration point) in
that GDD cannot be satisfied without this architectural decision?
If the decision is foundational (no GDD drives it directly), ask:
- Which GDD systems will this decision constrain or enable?
This GDD linkage becomes a mandatory "GDD Requirements Addressed" section
in the ADR. Do not skip it.
**Does this ADR have ordering constraints?** Ask:
- Does this decision depend on any other ADR that isn't yet Accepted? (If
so, this ADR cannot be safely implemented until that one is resolved.)
- Does accepting this ADR unlock or unblock any other pending decisions?
- Does this ADR block any specific epic or story from starting?
Record the answers in the **ADR Dependencies** section. If no ordering
constraints exist, write "None" in each field.
---
## 4. Generate the ADR
Following this format:
```markdown
# ADR-[NNNN]: [Title]
@ -27,6 +109,26 @@ When this skill is invoked:
## Date
[Date of decision]
## Engine Compatibility
| Field | Value |
|-------|-------|
| **Engine** | [e.g. Godot 4.6] |
| **Domain** | [Physics / Rendering / UI / Audio / Navigation / Animation / Networking / Core / Input] |
| **Knowledge Risk** | [LOW / MEDIUM / HIGH — from VERSION.md] |
| **References Consulted** | [List engine-reference docs read, e.g. `docs/engine-reference/godot/modules/physics.md`] |
| **Post-Cutoff APIs Used** | [Any APIs from post-LLM-cutoff versions this decision depends on, or "None"] |
| **Verification Required** | [Specific behaviours to test before shipping, or "None"] |
## ADR Dependencies
| Field | Value |
|-------|-------|
| **Depends On** | [ADR-NNNN (must be Accepted before this can be implemented), or "None"] |
| **Enables** | [ADR-NNNN (this ADR unlocks that decision), or "None"] |
| **Blocks** | [Epic/Story name — cannot start until this ADR is Accepted, or "None"] |
| **Ordering Note** | [Any sequencing constraint that isn't captured above] |
## Context
### Problem Statement

384
.claude/skills/architecture-review/SKILL.md Normal file
View file

@ -0,0 +1,384 @@
---
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
context: fork
agent: technical-director
---
# 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
---
## Phase 1: Load Everything
Read all inputs before analysis:
### Design Documents
- All GDDs in `design/gdd/` — read every file completely
- `design/gdd/systems-index.md` — the authoritative list of systems
### Architecture Documents
- All 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]."
---
## Phase 2: Extract Technical Requirements from Every GDD
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 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
```
---
## 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."
Ask: "Should I flag these GDDs for revision in the systems index?"
- If yes: update the relevant systems' Status field to "Needs Revision (Architecture Feedback)"
and note the specific conflict in a comment. Ask for approval before writing.
---
## 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
Ask: "May I write this review to `docs/architecture/architecture-review-[date].md`?"
Also ask: "May I update `docs/architecture/architecture-traceability.md` with the
current matrix? This is the living index that future reviews update incrementally."
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:
1. **Immediate actions**: List the top 3 ADRs to create (highest-impact gaps first,
Foundation layer before Feature layer)
2. **Gate guidance**: "When all blocking issues are resolved, run `/gate-check
pre-production` to advance"
3. **Rerun trigger**: "Re-run `/architecture-review` after each new ADR is written
to verify coverage improves"
---
## 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. **Ask before writing** — always confirm before writing the report file
5. **Non-blocking** — the verdict is advisory; the user decides whether to continue
despite CONCERNS or even FAIL findings

352
.claude/skills/create-architecture/SKILL.md Normal file
View file

@ -0,0 +1,352 @@
---
name: create-architecture
description: "Guided, section-by-section authoring of the master architecture document for the game. Reads all GDDs, the systems index, existing ADRs, and the engine reference library to produce a complete architecture blueprint before any code is written. Engine-version-aware: flags knowledge gaps and validates decisions against the pinned engine version."
argument-hint: "[focus-area: full | layers | data-flow | api-boundaries | adr-audit]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Bash
context: fork
agent: technical-director
---
# Create Architecture
This skill produces `docs/architecture/architecture.md` — the master architecture
document that translates all approved GDDs into a concrete technical blueprint.
It sits between design and implementation, and must exist before sprint planning begins.
**Distinct from `/architecture-decision`**: ADRs record individual point decisions.
This skill creates the whole-system blueprint that gives ADRs their context.
**Argument modes:**
- **No argument / `full`**: Full guided walkthrough — all sections, start to finish
- **`layers`**: Focus on the system layer diagram only
- **`data-flow`**: Focus on data flow between modules only
- **`api-boundaries`**: Focus on API boundary definitions only
- **`adr-audit`**: Audit existing ADRs for engine compatibility gaps only
---
## Phase 0: Load All Context
Before anything else, load the full project context in this order:
### 0a. Engine Context (Critical)
Read the engine reference library completely:
1. `docs/engine-reference/[engine]/VERSION.md`
→ Extract: engine name, version, LLM cutoff, post-cutoff risk levels
2. `docs/engine-reference/[engine]/breaking-changes.md`
→ Extract: all HIGH and MEDIUM risk changes
3. `docs/engine-reference/[engine]/deprecated-apis.md`
→ Extract: APIs to avoid
4. `docs/engine-reference/[engine]/current-best-practices.md`
→ Extract: post-cutoff best practices that differ from training data
5. All files in `docs/engine-reference/[engine]/modules/`
→ Extract: current API patterns per domain
If no engine is configured, stop and prompt:
> "No engine is configured. Run `/setup-engine` first. Architecture cannot be
> written without knowing which engine and version you are targeting."
### 0b. Design Context + Technical Requirements Extraction
Read all approved design documents and extract technical requirements from each:
1. `design/gdd/game-concept.md` — game pillars, genre, core loop
2. `design/gdd/systems-index.md` — all systems, dependencies, priority tiers
3. `.claude/docs/technical-preferences.md` — naming conventions, performance budgets,
allowed libraries, forbidden patterns
4. **Every GDD in `design/gdd/`** — for each, extract technical requirements:
- Data structures implied by the game rules
- Performance constraints stated or implied
- Engine capabilities the system requires
- Cross-system communication patterns (what talks to what, how)
- State that must persist (save/load implications)
- Threading or timing requirements
Build a **Technical Requirements Baseline** — a flat list of all extracted
requirements across all GDDs, numbered `TR-[gdd-slug]-[NNN]`. This is the
complete set of what the architecture must cover. Present it as:
```
## Technical Requirements Baseline
Extracted from [N] GDDs | [X] total requirements
| Req ID | GDD | System | Requirement | Domain |
|--------|-----|--------|-------------|--------|
| TR-combat-001 | combat.md | Combat | Hitbox detection per-frame | Physics |
| TR-combat-002 | combat.md | Combat | Combo state machine | Core |
| TR-inventory-001 | inventory.md | Inventory | Item persistence | Save/Load |
```
This baseline feeds into every subsequent phase. No GDD requirement should be
left without an architectural decision to support it by the end of this session.
### 0c. Existing Architecture Decisions
Read all files in `docs/architecture/` to understand what has already been decided.
List any ADRs found and their domains.
### 0d. Generate Knowledge Gap Inventory
Before proceeding, display a structured summary:
```
## Engine Knowledge Gap Inventory
Engine: [name + version]
LLM Training Covers: up to approximately [version]
Post-Cutoff Versions: [list]
### HIGH RISK Domains (must verify against engine reference before deciding)
- [Domain]: [Key changes]
### MEDIUM RISK Domains (verify key APIs)
- [Domain]: [Key changes]
### LOW RISK Domains (in training data, likely reliable)
- [Domain]: [no significant post-cutoff changes]
### Systems from GDD that touch HIGH/MEDIUM risk domains:
- [GDD system name] → [domain] → [risk level]
```
Ask: "This inventory identifies [N] systems in HIGH RISK engine domains. Shall I
continue building the architecture with these warnings flagged throughout?"
---
## Phase 1: System Layer Mapping
Map every system from `systems-index.md` into an architecture layer. The standard
game architecture layers are:
```
┌─────────────────────────────────────────────┐
│ PRESENTATION LAYER │ ← UI, HUD, menus, VFX, audio
├─────────────────────────────────────────────┤
│ FEATURE LAYER │ ← gameplay systems, AI, quests
├─────────────────────────────────────────────┤
│ CORE LAYER │ ← physics, input, combat, movement
├─────────────────────────────────────────────┤
│ FOUNDATION LAYER │ ← engine integration, save/load,
│ │ scene management, event bus
├─────────────────────────────────────────────┤
│ PLATFORM LAYER │ ← OS, hardware, engine API surface
└─────────────────────────────────────────────┘
```
For each GDD system, ask:
- Which layer does it belong to?
- What are its module boundaries?
- What does it own exclusively? (data, state, behaviour)
Present the proposed layer assignment and ask for approval before proceeding to
the next section. Write the approved layer map immediately to the skeleton file.
**Engine awareness check**: For each system assigned to the Core and Foundation
layers, flag if it touches a HIGH or MEDIUM risk engine domain. Show the relevant
engine reference excerpt inline.
---
## Phase 2: Module Ownership Map
For each module defined in Phase 1, define ownership:
- **Owns**: what data and state this module is solely responsible for
- **Exposes**: what other modules may read or call
- **Consumes**: what it reads from other modules
- **Engine APIs used**: which specific engine classes/nodes/signals this module
calls directly (with version and risk level noted)
Format as a table per layer, then as an ASCII dependency diagram.
**Engine awareness check**: For every engine API listed, verify against the
relevant module reference doc. If an API is post-cutoff, flag it:
```
⚠️ [ClassName.method()] — Godot 4.6 (post-cutoff, HIGH risk)
Verified against: docs/engine-reference/godot/modules/[domain].md
Behaviour confirmed: [yes / NEEDS VERIFICATION]
```
Get user approval on the ownership map before writing.
---
## Phase 3: Data Flow
Define how data moves between modules during key game scenarios. Cover at minimum:
1. **Frame update path**: Input → Core systems → State → Rendering
2. **Event/signal path**: How systems communicate without tight coupling
3. **Save/load path**: What state is serialised, which module owns serialisation
4. **Initialisation order**: Which modules must boot before others
Use ASCII sequence diagrams where helpful. For each data flow:
- Name the data being transferred
- Identify the producer and consumer
- State whether this is synchronous call, signal/event, or shared state
- Flag any data flows that cross thread boundaries
Get user approval per scenario before writing.
---
## Phase 4: API Boundaries
Define the public contracts between modules. For each boundary:
- What is the interface a module exposes to the rest of the system?
- What are the entry points (functions/signals/properties)?
- What invariants must callers respect?
- What must the module guarantee to callers?
Write in pseudocode or the project's actual language (from technical preferences).
These become the contracts programmers implement against.
**Engine awareness check**: If any interface uses engine-specific types (e.g.
`Node`, `Resource`, `Signal` in Godot), flag the version and verify the type
exists and has not changed signature in the target engine version.
---
## Phase 5: ADR Audit + Traceability Check
Review all existing ADRs from Phase 0c against both the architecture built in
Phases 1-4 AND the Technical Requirements Baseline from Phase 0b.
### ADR Quality Check
For each ADR:
- [ ] Does it have an Engine Compatibility section?
- [ ] Is the engine version recorded?
- [ ] Are post-cutoff APIs flagged?
- [ ] Does it have a "GDD Requirements Addressed" section?
- [ ] Does it conflict with the layer/ownership decisions made in this session?
- [ ] Is it still valid for the pinned engine version?
| ADR | Engine Compat | Version | GDD Linkage | Conflicts | Valid |
|-----|--------------|---------|-------------|-----------|-------|
| ADR-0001: [title] | ✅/❌ | ✅/❌ | ✅/❌ | None/[conflict] | ✅/⚠️ |
### Traceability Coverage Check
Map every requirement from the Technical Requirements Baseline to existing ADRs.
For each requirement, check if any ADR's "GDD Requirements Addressed" section
or decision text covers it:
| Req ID | Requirement | ADR Coverage | Status |
|--------|-------------|--------------|--------|
| TR-combat-001 | Hitbox detection per-frame | ADR-0003 | ✅ |
| TR-combat-002 | Combo state machine | — | ❌ GAP |
Count: X covered, Y gaps. For each gap, it becomes a **Required New ADR**.
### Required New ADRs
List all decisions made during this architecture session (Phases 1-4) that do
not yet have a corresponding ADR, PLUS all uncovered Technical Requirements.
Group by layer — Foundation first:
**Foundation Layer (must create before any coding):**
- `/architecture-decision [title]` → covers: TR-[id], TR-[id]
**Core Layer:**
- `/architecture-decision [title]` → covers: TR-[id]
---
## Phase 6: Missing ADR List
Based on the full architecture, produce a complete list of ADRs that should exist
but don't yet. Group by priority:
**Must have before coding starts (Foundation & Core decisions):**
- [e.g. "Scene management and scene loading strategy"]
- [e.g. "Event bus vs direct signal architecture"]
**Should have before the relevant system is built:**
- [e.g. "Inventory serialisation format"]
**Can defer to implementation:**
- [e.g. "Specific shader technique for water"]
---
## Phase 7: Write the Master Architecture Document
Once all sections are approved, write the complete document to
`docs/architecture/architecture.md`.
Ask: "May I write the master architecture document to `docs/architecture/architecture.md`?"
The document structure:
```markdown
# [Game Name] — Master Architecture
## Document Status
- Version: [N]
- Last Updated: [date]
- Engine: [name + version]
- GDDs Covered: [list]
- ADRs Referenced: [list]
## Engine Knowledge Gap Summary
[Condensed from Phase 0d inventory — HIGH/MEDIUM risk domains and their implications]
## System Layer Map
[From Phase 1]
## Module Ownership
[From Phase 2]
## Data Flow
[From Phase 3]
## API Boundaries
[From Phase 4]
## ADR Audit
[From Phase 5]
## Required ADRs
[From Phase 6]
## Architecture Principles
[3-5 key principles that govern all technical decisions for this project,
derived from the game concept, GDDs, and technical preferences]
## Open Questions
[Decisions deferred — must be resolved before the relevant layer is built]
```
---
## Phase 8: Handoff
After writing the document, provide a clear handoff:
1. **Run these ADRs next** (from Phase 6, prioritised): list the top 3
2. **Gate check**: "The master architecture document is complete. Run `/gate-check
pre-production` when all required ADRs are also written."
3. **Update session state**: Write a summary to `production/session-state/active.md`
---
## Collaborative Protocol
This skill follows the collaborative design principle at every phase:
1. **Load context silently** — do not narrate file reads
2. **Present findings** — show the knowledge gap inventory and layer proposals
3. **Ask before deciding** — present options for each architectural choice
4. **Get approval before writing** — each phase section is written only after
user approves the content
5. **Incremental writing** — write each approved section immediately; do not
accumulate everything and write at the end. This survives session crashes.
Never make a binding architectural decision without user input. If the user is
unsure, present 2-4 options with pros/cons before asking them to decide.

247
.claude/skills/create-control-manifest/SKILL.md Normal file
View file

@ -0,0 +1,247 @@
---
name: create-control-manifest
description: "After architecture is complete, produces a flat actionable rules sheet for programmers — what you must do, what you must never do, per system and per layer. Extracted from all Accepted ADRs, technical preferences, and engine reference docs. More immediately actionable than ADRs (which explain why)."
argument-hint: "[update — regenerate from current ADRs]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write
context: fork
agent: technical-director
---
# Create Control Manifest
The Control Manifest is a flat, actionable rules sheet for programmers. It
answers "what do I do?" and "what must I never do?" — organized by architectural
layer, extracted from all Accepted ADRs, technical preferences, and engine
reference docs. Where ADRs explain *why*, the manifest tells you *what*.
**Output:** `docs/architecture/control-manifest.md`
**When to run:** After `/architecture-review` passes and ADRs are in Accepted
status. Re-run whenever new ADRs are accepted or existing ADRs are revised.
---
## 1. Load All Inputs
### ADRs
- Glob `docs/architecture/adr-*.md` and read every file
- Filter to only Accepted ADRs (Status: Accepted) — skip Proposed, Deprecated,
Superseded
- Note the ADR number and title for every rule sourced
### Technical Preferences
- Read `.claude/docs/technical-preferences.md`
- Extract: naming conventions, performance budgets, approved libraries/addons,
forbidden patterns
### Engine Reference
- Read `docs/engine-reference/[engine]/VERSION.md` for engine + version
- Read `docs/engine-reference/[engine]/deprecated-apis.md` — these become
forbidden API entries
- Read `docs/engine-reference/[engine]/current-best-practices.md` if it exists
Report: "Loaded [N] Accepted ADRs, engine: [name + version]."
---
## 2. Extract Rules from Each ADR
For each Accepted ADR, extract:
### Required Patterns (from "Implementation Guidelines" section)
- Every "must", "should", "required to", "always" statement
- Every specific pattern or approach mandated
### Forbidden Approaches (from "Alternatives Considered" sections)
- Every alternative that was explicitly rejected — *why* it was rejected becomes
the rule ("never use X because Y")
- Any anti-patterns explicitly called out
### Performance Guardrails (from "Performance Implications" section)
- Budget constraints: "max N ms per frame for this system"
- Memory limits: "this system must not exceed N MB"
### Engine API Constraints (from "Engine Compatibility" section)
- Post-cutoff APIs that require verification
- Verified behaviours that differ from default LLM assumptions
- API fields or methods that behave differently in the pinned engine version
### Layer Classification
Classify each rule by the architectural layer of the system it governs:
- **Foundation**: Scene management, event architecture, save/load, engine init
- **Core**: Core gameplay loops, main player systems, physics/collision
- **Feature**: Secondary systems, secondary mechanics, AI
- **Presentation**: Rendering, audio, UI, VFX, shaders
If an ADR spans multiple layers, duplicate the rule into each relevant layer.
---
## 3. Add Global Rules
Combine rules that apply to all layers:
### From technical-preferences.md:
- Naming conventions (classes, variables, signals/events, files, constants)
- Performance budgets (target framerate, frame budget, draw call limits, memory ceiling)
### From deprecated-apis.md:
- All deprecated APIs → Forbidden API entries
### From current-best-practices.md (if available):
- Engine-recommended patterns → Required entries
### From technical-preferences.md forbidden patterns:
- Copy any "Forbidden Patterns" entries directly
---
## 4. Present Rules Summary Before Writing
Before writing the manifest, present a summary to the user:
```
## Control Manifest Preview
Engine: [name + version]
ADRs covered: [list ADR numbers]
Total rules extracted:
- Foundation layer: [N] required, [M] forbidden, [P] guardrails
- Core layer: [N] required, [M] forbidden, [P] guardrails
- Feature layer: ...
- Presentation layer: ...
- Global: [N] naming conventions, [M] forbidden APIs, [P] approved libraries
```
Ask: "Does this look complete? Any rules to add or remove before I write the manifest?"
---
## 5. Write the Control Manifest
Ask: "May I write this to `docs/architecture/control-manifest.md`?"
Format:
```markdown
# Control Manifest
> **Engine**: [name + version]
> **Last Updated**: [date]
> **ADRs Covered**: [ADR-NNNN, ADR-MMMM, ...]
> **Status**: [Active — regenerate with `/create-control-manifest update` when ADRs change]
This manifest is a programmer's quick-reference extracted from all Accepted ADRs,
technical preferences, and engine reference docs. For the reasoning behind each
rule, see the referenced ADR.
---
## Foundation Layer Rules
*Applies to: scene management, event architecture, save/load, engine initialisation*
### Required Patterns
- **[rule]** — source: [ADR-NNNN]
- **[rule]** — source: [ADR-NNNN]
### Forbidden Approaches
- **Never [anti-pattern]** — [brief reason] — source: [ADR-NNNN]
### Performance Guardrails
- **[system]**: max [N]ms/frame — source: [ADR-NNNN]
---
## Core Layer Rules
*Applies to: core gameplay loop, main player systems, physics, collision*
### Required Patterns
...
### Forbidden Approaches
...
### Performance Guardrails
...
---
## Feature Layer Rules
*Applies to: secondary mechanics, AI systems, secondary features*
### Required Patterns
...
### Forbidden Approaches
...
---
## Presentation Layer Rules
*Applies to: rendering, audio, UI, VFX, shaders, animations*
### Required Patterns
...
### Forbidden Approaches
...
---
## Global Rules (All Layers)
### Naming Conventions
| Element | Convention | Example |
|---------|-----------|---------|
| Classes | [from technical-preferences] | [example] |
| Variables | [from technical-preferences] | [example] |
| Signals/Events | [from technical-preferences] | [example] |
| Files | [from technical-preferences] | [example] |
| Constants | [from technical-preferences] | [example] |
### Performance Budgets
| Target | Value |
|--------|-------|
| Framerate | [from technical-preferences] |
| Frame budget | [from technical-preferences] |
| Draw calls | [from technical-preferences] |
| Memory ceiling | [from technical-preferences] |
### Approved Libraries / Addons
- [library] — approved for [purpose]
### Forbidden APIs ([engine version])
These APIs are deprecated or unverified for [engine + version]:
- `[api name]` — deprecated since [version] / unverified post-cutoff
- Source: `docs/engine-reference/[engine]/deprecated-apis.md`
### Cross-Cutting Constraints
- [constraint that applies everywhere, regardless of layer]
```
---
## 6. Suggest Next Steps
After writing the manifest:
- If epics/stories don't exist yet: "Run `/create-epics-stories` — programmers
can now use this manifest when writing story implementation notes."
- If this is a regeneration (manifest already existed): "Updated. Recommend
notifying the team of changed rules — especially any new Forbidden entries."
---
## Collaborative Protocol
1. **Load silently** — read all inputs before presenting anything
2. **Show the summary first** — let the user see the scope before writing
3. **Ask before writing** — always confirm before creating or overwriting the manifest
4. **Source every rule** — never add a rule that doesn't trace to an ADR, a
technical preference, or an engine reference doc
5. **No interpretation** — extract rules as stated in ADRs; do not paraphrase
in ways that change meaning

300
.claude/skills/create-epics-stories/SKILL.md Normal file
View file

@ -0,0 +1,300 @@
---
name: create-epics-stories
description: "Translate approved GDDs + architecture + ADRs into implementable epics and stories. Each story embeds the GDD requirement it satisfies, the ADR governing implementation, acceptance criteria, engine compatibility notes, and control manifest rules. Programmers need nothing else to implement a story correctly."
argument-hint: "[system-name | layer: foundation|core|feature|presentation | all]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write
context: fork
agent: technical-director
---
# Create Epics & Stories
This skill translates the approved design and architecture into implementable
work units. Each **epic** maps to one architectural module. Each **story** is a
single implementable behaviour — small enough for one session, self-contained,
and fully traceable to the GDD requirement it satisfies and the ADR that governs
how to implement it.
**Output:** `production/epics/[epic-slug]/`
**When to run:** After `/architecture-review` passes and `/create-control-manifest`
has been run. All MVP-tier GDDs should be complete and reviewed.
---
## 1. Parse Arguments
**Modes:**
- `/create-epics-stories all` — process all systems in layer order
- `/create-epics-stories layer: foundation` — process Foundation layer only
- `/create-epics-stories [system-name]` — process one specific system
- No argument — ask the user which mode to use
If no argument, use `AskUserQuestion`:
- "What would you like to create epics for?"
- Options: "All systems (Foundation → Presentation)", "Foundation layer only",
"Core layer only", "A specific system", "Feature + Presentation layers"
---
## 2. Load All Inputs
Read everything before generating any output:
### Design Documents
- `design/gdd/systems-index.md` — authoritative system list, layers, status
- All GDDs in `design/gdd/` — read every file with "Approved" or "Designed" status
- For each GDD, extract:
- System name and layer (from systems-index.md)
- All acceptance criteria (these become story acceptance criteria)
- All technical requirements (these trace to ADR coverage)
- Dependencies on other systems
### Architecture Documents
- `docs/architecture/architecture.md` — module ownership and API boundaries
- All Accepted ADRs in `docs/architecture/adr-*.md` — read "GDD Requirements
Addressed", "Implementation Guidelines", "Engine Compatibility", and
"ADR Dependencies" sections
- `docs/architecture/control-manifest.md` if it exists — extract layer-specific
rules to embed in stories
### Engine Reference
- `docs/engine-reference/[engine]/VERSION.md` — engine name + version + risk levels
Report: "Loaded [N] GDDs, [M] ADRs, control manifest: [exists/missing],
engine: [name + version]."
---
## 3. Determine Processing Order
Process systems in dependency-safe layer order:
1. **Foundation** (no dependencies)
2. **Core** (depends on Foundation)
3. **Feature** (depends on Core)
4. **Presentation** (depends on Feature + Core)
Within each layer, process systems in the order they appear in systems-index.md.
For each system, determine the corresponding epic:
- Epic = one architectural module from `architecture.md` that implements this system
- If a system doesn't map cleanly to a single module, present options to the user
---
## 4. For Each System: Define the Epic
Present to the user before creating stories:
```
## Epic [N]: [System Name]
**Layer**: [Foundation / Core / Feature / Presentation]
**GDD**: design/gdd/[filename].md
**Architecture Module**: [module name from architecture.md]
**GDD Requirements Traced by ADRs**: [list TR-IDs that have ADR coverage]
**Untraceable Requirements**: [list TR-IDs with no ADR — these need ADRs first]
**Governing ADRs**: [ADR-NNNN, ADR-MMMM, ...]
**Engine Risk**: [LOW/MEDIUM/HIGH — highest risk among governing ADRs]
```
Ask: "Shall I break Epic [N]: [name] into stories?"
- Options: "Yes, break it down", "Skip this epic", "Pause — I need to write ADRs first"
If there are untraced requirements (no ADR covers them), warn:
> "⚠️ [N] requirements in [system] have no ADR. Stories for these cannot embed
> implementation guidance. Consider running `/architecture-decision` first, or
> I can create stories with a placeholder note to add ADR guidance later."
---
## 5. Break Each Epic into Stories
For each epic, decompose the GDD's acceptance criteria into stories:
**Story sizing rules:**
- One story = one implementable behaviour from the GDD
- Small enough to complete in a single focused session (~2-4 hours of focused work)
- Self-contained — no story depends on in-progress work from another story in
the same epic (stories within an epic run sequentially; they can depend on
previous stories being DONE, not in-progress)
**Story identification process:**
1. Read every acceptance criterion in the GDD
2. Group related criteria that require the same core implementation
3. Each group = one story
4. Order stories within the epic: foundation behaviour first, edge cases last
For each story, map:
- **GDD requirement**: Which specific acceptance criterion does this satisfy?
- **TR-ID**: The technical requirement ID (from `/architecture-review` traceability matrix, if run)
- **Governing ADR**: Which Accepted ADR tells the programmer how to implement this?
- **Engine risk**: Inherited from the ADR's Knowledge Risk field
- **Control manifest rules**: Which layer rules apply?
---
## 6. Generate Story Files
For each story, produce a story file embedding full context:
```markdown
# Story [NNN]: [title]
> **Epic**: [epic name]
> **Status**: Ready
> **Layer**: [Foundation / Core / Feature / Presentation]
## Context
**GDD**: `design/gdd/[filename].md`
**Requirement**: TR-[GDD]-[NNN]: [requirement text from GDD]
**ADR Governing Implementation**: [ADR-NNNN: title]
**ADR Decision Summary**: [1-2 sentence summary of what the ADR decided]
**Engine**: [name + version] | **Risk**: [LOW / MEDIUM / HIGH]
**Engine Notes**: [relevant text from the ADR's Engine Compatibility section,
especially Post-Cutoff APIs Used and Verification Required fields]
**Control Manifest Rules (this layer)**:
- Required: [relevant required pattern from manifest]
- Forbidden: [relevant forbidden approach from manifest]
- Guardrail: [relevant performance guardrail]
---
## Acceptance Criteria
*From GDD `design/gdd/[filename].md`, scoped to this story:*
- [ ] [criterion 1 — directly from GDD, scoped to this story's behaviour]
- [ ] [criterion 2]
- [ ] [performance criterion if applicable]
---
## Implementation Notes
*Derived from ADR-NNNN Implementation Guidelines:*
[Specific guidance for the programmer. This should be the ADR's Implementation
Guidelines section, filtered to what's relevant for this story. Do not
paraphrase in ways that change meaning.]
---
## Out of Scope
*These are handled by neighbouring stories — do not implement here:*
- [Story NNN+1]: [what it handles]
- [Other epic story]: [what it handles]
This boundary prevents scope creep and keeps stories independently reviewable.
---
## Dependencies
- Depends on: [Story NNN-1 must be DONE, or "None"]
- Unlocks: [Story NNN+1, or "None"]
```
---
## 7. Approval Before Writing
For each epic, after all stories are drafted, present a summary:
```
Epic [N]: [name]
Stories: [N total]
Story 001: [title] — [1-line summary]
Story 002: [title] — [1-line summary]
...
```
Ask: "May I write these [N] stories and the epic index to
`production/epics/[epic-slug]/`?"
---
## 8. Write Output Files
After approval, write:
### Story files
`production/epics/[epic-slug]/story-[NNN]-[slug].md`
### Epic index
`production/epics/[epic-slug]/EPIC.md`:
```markdown
# Epic: [name]
> **Layer**: [Foundation / Core / Feature / Presentation]
> **GDD**: design/gdd/[filename].md
> **Status**: Ready
> **Stories**: [N total]
## Overview
[1 paragraph describing what this epic implements]
## Stories
| # | Story | Status | ADR |
|---|-------|--------|-----|
| 001 | [title] | Ready | ADR-NNNN |
| 002 | [title] | Ready | ADR-MMMM |
## Definition of Done
This epic is complete when:
- All stories are implemented and reviewed
- All acceptance criteria from [GDD filename] are passing
- No Foundation or Core layer stories have open blockers
```
### Master epics index
`production/epics/index.md` (create or update):
```markdown
# Epics Index
Last Updated: [date]
Engine: [name + version]
| Epic | Layer | System | Stories | Status |
|------|-------|--------|---------|--------|
| [name] | Foundation | [system] | [N] | Ready |
```
---
## 9. Gate-Check Integration
After writing all epics for the requested scope, remind the user:
- **Foundation + Core complete**: Pre-Production → Production gate requires
Foundation and Core layer epics. Run `/gate-check production` to validate.
- **All layers complete**: Full epic coverage achieved. The sprint plan can now
reference real story file paths instead of GDD references.
---
## Collaborative Protocol
1. **Load silently** — read all inputs before presenting the first epic
2. **One epic at a time** — present each epic before creating stories; don't
batch all epics and ask once
3. **Warn on gaps** — flag untraced requirements before proceeding; let the user
decide whether to pause for ADRs or proceed with placeholders
4. **Ask before writing** — per-epic approval before writing story files
5. **No invention** — all acceptance criteria come from GDDs; all implementation
notes come from ADRs; all rules come from the control manifest. Never invent
requirements or rules that don't trace to a source document.
6. **Preserve exact quotes** — when embedding GDD requirements and ADR guidelines,
quote them exactly; do not paraphrase in ways that change meaning

65
.claude/skills/design-system/SKILL.md
View file

@ -74,6 +74,71 @@ If any upstream dependencies are undesigned, warn:
> its interface. Consider designing it first, or we can define the expected
> contract and flag it as provisional."
### 2e: Technical Feasibility Pre-Check
Before asking the user to begin designing, load engine context and surface any
constraints or knowledge gaps that will shape the design.
**Step 1 — Determine the engine domain for this system:**
Map the system's category (from systems-index.md) to an engine domain:
| System Category | Engine Domain |
|----------------|--------------|
| Combat, physics, collision | Physics |
| Rendering, visual effects, shaders | Rendering |
| UI, HUD, menus | UI |
| Audio, sound, music | Audio |
| AI, pathfinding, behavior trees | Navigation / Scripting |
| Animation, IK, rigs | Animation |
| Networking, multiplayer, sync | Networking |
| Input, controls, keybinding | Input |
| Save/load, persistence, data | Core |
| Dialogue, quests, narrative | Scripting |
**Step 2 — Read engine context (if available):**
- Read `.claude/docs/technical-preferences.md` to identify the engine and version
- If engine is configured, read `docs/engine-reference/[engine]/VERSION.md`
- Read `docs/engine-reference/[engine]/modules/[domain].md` if it exists
- Read `docs/engine-reference/[engine]/breaking-changes.md` for domain-relevant entries
- Glob `docs/architecture/adr-*.md` and read any ADRs whose domain matches
(check the Engine Compatibility table's "Domain" field)
**Step 3 — Present the Feasibility Brief:**
If engine reference docs exist, present before starting design:
```
## Technical Feasibility Brief: [System Name]
Engine: [name + version]
Domain: [domain]
### Known Engine Capabilities (verified for [version])
- [capability relevant to this system]
- [capability 2]
### Engine Constraints That Will Shape This Design
- [constraint from engine-reference or existing ADR]
### Knowledge Gaps (verify before committing to these)
- [post-cutoff feature this design might rely on — mark HIGH/MEDIUM risk]
### Existing ADRs That Constrain This System
- ADR-XXXX: [decision summary] — means [implication for this GDD]
(or "None yet")
```
If no engine reference docs exist (engine not yet configured), show a short note:
> "No engine configured yet — skipping technical feasibility check. Run
> `/setup-engine` before moving to architecture if you haven't already."
**Step 4 — Ask before proceeding:**
Use `AskUserQuestion`:
- "Any constraints to add before we begin, or shall we proceed with these noted?"
- Options: "Proceed with these noted", "Add a constraint first", "I need to check the engine docs — pause here"
---
Use `AskUserQuestion`:
- "Ready to start designing [system-name]?"
- Options: "Yes, let's go", "Show me more context first", "Design a dependency first"

102
.claude/skills/gate-check/SKILL.md
View file

@ -58,12 +58,16 @@ The project progresses through these stages:
**Required Artifacts:**
- [ ] Systems index exists at `design/gdd/systems-index.md` with at least MVP systems enumerated
- [ ] At least 1 GDD in `design/gdd/` (beyond game-concept.md and systems-index.md)
- [ ] All MVP-tier GDDs exist in `design/gdd/` and individually pass `/design-review`
- [ ] A cross-GDD review report exists in `design/gdd/` (from `/review-all-gdds`)
**Quality Checks:**
- [ ] GDD(s) pass design review (8 required sections present)
- [ ] System dependencies are mapped in the systems index
- [ ] All MVP GDDs pass individual design review (8 required sections, no MAJOR REVISION NEEDED verdict)
- [ ] `/review-all-gdds` verdict is not FAIL (cross-GDD consistency and design theory checks pass)
- [ ] All cross-GDD consistency issues flagged by `/review-all-gdds` are resolved or explicitly accepted
- [ ] System dependencies are mapped in the systems index and are bidirectionally consistent
- [ ] MVP priority tier is defined
- [ ] No stale GDD references flagged (older GDDs updated to reflect decisions made in later GDDs)
---
@ -72,12 +76,32 @@ The project progresses through these stages:
**Required Artifacts:**
- [ ] Engine chosen (CLAUDE.md Technology Stack is not `[CHOOSE]`)
- [ ] Technical preferences configured (`.claude/docs/technical-preferences.md` populated)
- [ ] At least 1 Architecture Decision Record in `docs/architecture/`
- [ ] Engine reference docs exist in `docs/engine-reference/`
- [ ] At least 3 Architecture Decision Records in `docs/architecture/` covering
Foundation-layer systems (scene management, event architecture, save/load)
- [ ] Engine reference docs exist in `docs/engine-reference/[engine]/`
- [ ] Master architecture document exists at `docs/architecture/architecture.md`
- [ ] Architecture traceability index exists at `docs/architecture/architecture-traceability.md`
- [ ] `/architecture-review` has been run (a review report file exists in `docs/architecture/`)
- [ ] `design/accessibility-requirements.md` exists with accessibility tier committed
- [ ] `design/ux/interaction-patterns.md` exists (pattern library initialized, even if minimal)
**Quality Checks:**
- [ ] Architecture decisions cover core systems (rendering, input, state management)
- [ ] Technical preferences have naming conventions and performance budgets set
- [ ] Accessibility tier is defined and documented (even "Basic" is acceptable — undefined is not)
- [ ] At least one screen's UX spec started (often the main menu or core HUD is designed during Technical Setup)
- [ ] All ADRs have an **Engine Compatibility section** with engine version stamped
- [ ] All ADRs have a **GDD Requirements Addressed section** with explicit GDD linkage
- [ ] No ADR references APIs listed in `docs/engine-reference/[engine]/deprecated-apis.md`
- [ ] All HIGH RISK engine domains (per VERSION.md) have been explicitly addressed
in the architecture document or flagged as open questions
- [ ] Architecture traceability matrix has **zero Foundation layer gaps**
(all Foundation requirements must have ADR coverage before Pre-Production)
**Engine Validation** (read `docs/engine-reference/[engine]/VERSION.md` first):
- [ ] ADRs that touch post-cutoff engine APIs are flagged with Knowledge Risk: HIGH/MEDIUM
- [ ] `/architecture-review` engine audit shows no deprecated API usage
- [ ] All ADRs agree on the same engine version (no stale version references)
---
@ -87,11 +111,44 @@ The project progresses through these stages:
- [ ] At least 1 prototype in `prototypes/` with a README
- [ ] First sprint plan exists in `production/sprints/`
- [ ] All MVP-tier GDDs from systems index are complete
- [ ] Master architecture document exists at `docs/architecture/architecture.md`
- [ ] At least 3 ADRs covering Foundation-layer decisions exist in `docs/architecture/`
- [ ] Control manifest exists at `docs/architecture/control-manifest.md`
(generated by `/create-control-manifest` from Accepted ADRs)
- [ ] Epics and stories defined in `production/epics/` with at least Foundation
and Core layer epics present (use `/create-epics-stories layer: foundation`
and `/create-epics-stories layer: core` to create them)
- [ ] Vertical Slice build exists and is playable (not just scope-defined)
- [ ] Vertical Slice has been playtested with at least 3 sessions (internal OK)
- [ ] Vertical Slice playtest report exists at `production/playtests/` or equivalent
- [ ] UX specs exist for key screens: main menu, core gameplay HUD (at `design/ux/`), pause menu
- [ ] HUD design document exists at `design/ux/hud.md` (if game has in-game HUD)
- [ ] All key screen UX specs have passed `/ux-review` (verdict APPROVED or NEEDS REVISION accepted)
**Quality Checks:**
- [ ] Prototype validates the core loop hypothesis
- [ ] Sprint plan references real work items from GDDs
- [ ] Vertical slice scope is defined
- [ ] **Core loop fun is validated** — playtest data confirms the central mechanic is enjoyable, not just functional. Explicitly check the Vertical Slice playtest report.
- [ ] UX specs cover all UI Requirements sections from MVP-tier GDDs
- [ ] Interaction pattern library documents patterns used in key screens
- [ ] Accessibility tier from `design/accessibility-requirements.md` is addressed in all key screen UX specs
- [ ] Sprint plan references real story file paths from `production/epics/`
(not just GDDs — stories must embed GDD req ID + ADR reference)
- [ ] **Vertical Slice is COMPLETE**, not just scoped — the build demonstrates the full core loop end-to-end. At least one complete [start → challenge → resolution] cycle works.
- [ ] Architecture document has no unresolved open questions in Foundation or Core layers
- [ ] All ADRs have Engine Compatibility sections stamped with the engine version
- [ ] All ADRs have ADR Dependencies sections (even if all fields are "None")
- [ ] `/bmad-bmm-check-implementation-readiness` has been run or equivalent manual
validation confirms GDDs + architecture + epics are coherent
- [ ] **Core fantasy is delivered** — at least one playtester independently described an experience that matches the Player Fantasy section of the core system GDDs (without being prompted).
**Vertical Slice Validation** (FAIL if any item is NO):
- [ ] A human has played through the core loop without developer guidance
- [ ] The game communicates what to do within the first 2 minutes of play
- [ ] No critical "fun blocker" bugs exist in the Vertical Slice build
- [ ] The core mechanic feels good to interact with (this is a subjective check — ask the user)
> **Note**: If any Vertical Slice Validation item is FAIL, the verdict is automatically FAIL
> regardless of other checks. Advancing without a validated Vertical Slice is the #1 cause of
> production failure in game development (per GDC postmortem data from 155 projects).
---
@ -102,13 +159,21 @@ The project progresses through these stages:
- [ ] All core mechanics from GDD are implemented (cross-reference `design/gdd/` with `src/`)
- [ ] Main gameplay path is playable end-to-end
- [ ] Test files exist in `tests/`
- [ ] At least 1 playtest report (or `/playtest-report` has been run)
- [ ] At least 3 distinct playtest sessions documented in `production/playtests/`
- [ ] Playtest reports cover: new player experience, mid-game systems, and difficulty curve
- [ ] Fun hypothesis from Game Concept has been explicitly validated or revised
**Quality Checks:**
- [ ] Tests are passing (run test suite via Bash)
- [ ] No critical/blocker bugs in any bug tracker or known issues
- [ ] Core loop plays as designed (compare to GDD acceptance criteria)
- [ ] Performance is within budget (check technical-preferences.md targets)
- [ ] Playtest findings have been reviewed and critical fun issues addressed (not just documented)
- [ ] No "confusion loops" identified — no point in the game where >50% of playtesters got stuck without knowing why
- [ ] Difficulty curve matches the Difficulty Curve design doc (if one exists at `design/difficulty-curve.md`)
- [ ] All implemented screens have corresponding UX specs (no "designed in-code" screens)
- [ ] Interaction pattern library is up-to-date with all patterns used in implementation
- [ ] Accessibility compliance verified against committed tier in `design/accessibility-requirements.md`
---
@ -229,9 +294,26 @@ Based on the verdict, suggest specific next steps:
- **No game concept?** → `/brainstorm` to create one
- **No systems index?** → `/map-systems` to decompose the concept into systems
- **Missing design docs?** → `/reverse-document` or delegate to `game-designer`
- **Missing ADRs?** → `/architecture-decision`
- **Small design change needed?** → `/quick-design` for changes under ~4 hours (bypasses full GDD pipeline)
- **No UX specs?** → `/ux-design [screen name]` to author specs, or `/team-ui [feature]` for full pipeline
- **UX specs not reviewed?** → `/ux-review [file]` or `/ux-review all` to validate
- **No accessibility requirements doc?** → create `design/accessibility-requirements.md` using the accessibility-requirements template
- **No interaction pattern library?** → `/ux-design patterns` to initialize it
- **GDDs not cross-reviewed?** → `/review-all-gdds` (run after all MVP GDDs are individually approved)
- **Cross-GDD consistency issues?** → fix flagged GDDs, then re-run `/review-all-gdds`
- **Missing ADRs?** → `/architecture-decision` for individual decisions
- **No master architecture doc?** → `/create-architecture` for the full blueprint
- **ADRs missing engine compatibility sections?** → Re-run `/architecture-decision`
or manually add Engine Compatibility sections to existing ADRs
- **Missing control manifest?** → `/create-control-manifest` (requires Accepted ADRs)
- **Missing epics/stories?** → `/create-epics-stories all` (requires control manifest)
- **Stories not implementation-ready?** → `/story-readiness` to validate stories before developers pick them up
- **Tests failing?** → delegate to `lead-programmer` or `qa-tester`
- **No playtest data?** → `/playtest-report`
- **Less than 3 playtest sessions?** → Run more playtests before advancing. Use `/playtest-report` to structure findings.
- **No Difficulty Curve doc?** → Consider creating one at `design/difficulty-curve.md` before polish
- **No player journey document?** → create `design/player-journey.md` using the player journey template
- **Need a quick sprint check?** → `/sprint-status` for current sprint progress snapshot
- **Performance unknown?** → `/perf-profile`
- **Not localized?** → `/localize`
- **Ready for release?** → `/launch-checklist`

213
.claude/skills/propagate-design-change/SKILL.md Normal file
View file

@ -0,0 +1,213 @@
---
name: propagate-design-change
description: "When a GDD is revised, scans all ADRs and the traceability index to identify which architectural decisions are now potentially stale. Produces a change impact report and guides the user through resolution."
argument-hint: "[path/to/changed-gdd.md]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Bash
context: fork
agent: technical-director
---
# Propagate Design Change
When a GDD changes, architectural decisions written against it may no longer be
valid. This skill finds every affected ADR, compares what the ADR assumed against
what the GDD now says, and guides the user through resolution.
**Usage:** `/propagate-design-change design/gdd/combat-system.md`
---
## 1. Validate Argument
A GDD path argument is **required**. If missing, fail with:
> "Usage: `/propagate-design-change design/gdd/[system].md`
> Provide the path to the GDD that was changed."
Verify the file exists. If not, fail with:
> "[path] not found. Check the path and try again."
---
## 2. Read the Changed GDD
Read the current GDD in full.
---
## 3. Read the Previous Version
Run git to get the previous committed version:
```bash
git show HEAD:design/gdd/[filename].md
```
If the file has no git history (new file), report:
> "No previous version in git — this appears to be a new GDD, not a revision.
> Nothing to propagate."
If git returns the previous version, do a conceptual diff:
- Identify sections that changed (new rules, removed rules, modified formulas,
changed acceptance criteria, changed tuning knobs)
- Identify sections that are unchanged
- Produce a change summary:
```
## Change Summary: [GDD filename]
Date of revision: [today]
Changed sections:
- [Section name]: [what changed — new rule, removed rule, formula modified, etc.]
Unchanged sections:
- [Section name]
Key changes affecting architecture:
- [Change 1 — likely to affect ADRs]
- [Change 2]
```
---
## 4. Load Architecture Inputs
Read all ADRs in `docs/architecture/`:
- For each ADR, read the full file
- Extract the "GDD Requirements Addressed" table
- Note which GDD documents and requirement IDs each ADR references
Read `docs/architecture/architecture-traceability.md` if it exists.
Report: "Loaded [N] ADRs. [M] reference [gdd filename]."
---
## 5. Impact Analysis
For each ADR that references the changed GDD:
Compare the ADR's "GDD Requirements Addressed" entries against the changed sections
of the GDD. For each referenced requirement:
1. **Locate the requirement** in the current GDD — does it still exist?
2. **Compare**: What did the GDD say when the ADR was written vs. what it says now?
3. **Assess the ADR decision**: Is the architectural decision still valid?
Classify each affected ADR as one of:
| Status | Meaning |
|--------|---------|
| ✅ **Still Valid** | The GDD change doesn't affect what this ADR decided |
| ⚠️ **Needs Review** | The GDD change may affect this ADR — human judgment needed |
| 🔴 **Likely Superseded** | The GDD change directly contradicts what this ADR assumed |
For each affected ADR, produce an impact entry:
```
### ADR-NNNN: [title]
Status: [Still Valid / Needs Review / Likely Superseded]
What the ADR assumed about this GDD:
"[relevant quote from the ADR's GDD Requirements Addressed section]"
What the GDD now says:
"[relevant quote from the current GDD]"
Assessment:
[Explanation of whether the ADR decision is still valid, and why]
Recommended action:
[Keep as-is | Review and update | Mark Superseded and write new ADR]
```
---
## 6. Present Impact Report
Present the full impact report to the user before asking for any action. Format:
```
## Design Change Impact Report
GDD: [filename]
Date: [today]
Changes detected: [N sections changed]
ADRs referencing this GDD: [M]
### Not Affected
[ADRs referencing this GDD whose decisions remain valid]
### Needs Review ([count])
[ADRs that may need updating]
### Likely Superseded ([count])
[ADRs whose assumptions are now contradicted]
```
---
## 7. Resolution Workflow
For each ADR marked "Needs Review" or "Likely Superseded", ask the user what to do:
Ask for each ADR in turn:
> "ADR-NNNN ([title]) — [status]. What would you like to do?"
> Options:
> - "Mark Superseded (I'll write a new ADR)" — updates ADR status line to `Superseded by: [pending]`
> - "Update in place (minor revision)" — opens the ADR for editing; note what to revise
> - "Keep as-is (the change doesn't actually affect this decision)"
> - "Skip for now (revisit later)"
For ADRs marked **Superseded**:
- Update the ADR's Status field: `Superseded by ADR-[next number] (pending — see change-impact-[date]-[system].md)`
- Ask: "May I update the status in [ADR filename]?"
---
## 8. Update Traceability Index
If `docs/architecture/architecture-traceability.md` exists:
- Add the changed GDD requirements to the "Superseded Requirements" table:
```markdown
## Superseded Requirements
| Date | GDD | Requirement | Changed To | ADRs Affected | Resolution |
|------|-----|-------------|------------|---------------|------------|
| [date] | [gdd] | [old requirement text] | [new requirement text] | ADR-NNNN | [Superseded/Updated/Valid] |
```
Ask: "May I update the traceability index?"
---
## 9. Output Change Impact Document
Ask: "May I write the change impact report to `docs/architecture/change-impact-[date]-[system-slug].md`?"
The document contains:
- The change summary from step 3
- The full impact analysis from step 5
- Resolution decisions made in step 7
- List of ADRs that need to be written or updated
---
## 10. Follow-Up Actions
Based on the resolution decisions, suggest:
- **ADRs marked Superseded**: "Run `/architecture-decision [title]` to write the
replacement ADR. Then re-run `/propagate-design-change` to verify coverage."
- **ADRs to update in place**: List the specific fields to update in each ADR
- **If many ADRs affected**: "Run `/architecture-review` after all ADRs are updated
to verify the full traceability matrix is still coherent."
---
## Collaborative Protocol
1. **Read silently** — compute the full impact before presenting anything
2. **Show the full report first** — let the user see the scope before asking for action
3. **Ask per-ADR** — don't batch decisions; each affected ADR may need different treatment
4. **Ask before writing** — always confirm before modifying any file
5. **Non-destructive** — never delete ADR content; only add "Superseded by" notes

263
.claude/skills/quick-design/SKILL.md Normal file
View file

@ -0,0 +1,263 @@
---
name: quick-design
description: "Lightweight design spec for small changes — tuning adjustments, minor mechanics, balance tweaks. Skips full GDD authoring when a system GDD already exists or the change is too small to warrant one. Produces a Quick Design Spec that embeds directly into story files."
argument-hint: "[brief description of the change]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit
context: fork
---
# Quick Design
This is the **lightweight design path** for changes that don't need a full GDD.
Full GDD authoring via `/design-system` is the heavyweight path. Use this skill
for work under approximately 4 hours of implementation — tuning adjustments,
minor behavioral tweaks, small additions to existing systems, or standalone
features too small to warrant a full document.
**Output:** `design/quick-specs/[name]-[date].md`
**When to run:** Anytime a change is too small for `/design-system` but too
meaningful to implement without a written rationale.
---
## 1. Classify the Change
First, read the argument and determine which category this change falls into:
- **Tuning** — changing numbers or balance values in an existing system with no
behavioral change (most minimal path). Example: "increase jump height from 5
to 6 units", "reduce enemy patrol speed by 10%".
- **Tweak** — a small behavioral change to an existing system that introduces no
new states, branches, or systems. Example: "make dash invincible on frame 1",
"allow combo to cancel into roll".
- **Addition** — adding a small mechanic to an existing system that may introduce
1-2 new states or interactions. Example: "add a parry window to the block
mechanic", "add a charge variant to the basic attack".
- **New Small System** — a standalone feature small enough that it has no
existing GDD and is under approximately one week of implementation work.
Example: "achievement popup system", "simple day/night visual cycle".
If the change does NOT fit these categories — it introduces a new system with
significant cross-system dependencies, requires more than one week of
implementation, or fundamentally alters an existing system's core rules — stop
and redirect to `/design-system` instead.
Present the classification to the user and confirm it is correct before
proceeding. If there is no argument, ask the user to describe the change.
---
## 2. Context Scan
Before drafting anything, read the relevant context:
- Search `design/gdd/` for the GDD most relevant to this change. Read the
sections that this change would affect.
- Read `design/gdd/systems-index.md` to understand where this system sits in
the dependency graph and what tier it belongs to.
- Check `design/quick-specs/` for any prior quick specs that touched this
system — avoid contradicting them.
- If this is a Tuning change, also check `assets/data/` for the data file that
holds the relevant values.
Report what was found: "Found GDD at [path]. Relevant section: [section name].
No conflicting quick specs found." (or note any conflicts found.)
---
## 3. Draft the Quick Design Spec
Use the appropriate spec format for the change category.
### For Tuning changes
Produce a single table:
```markdown
# Quick Design Spec: [Title]
**Type**: Tuning
**System**: [System name]
**GDD Reference**: `design/gdd/[filename].md` — Tuning Knobs section
**Date**: [today]
## Change
| Parameter | Old Value | New Value | Rationale |
|-----------|-----------|-----------|-----------|
| [param] | [old] | [new] | [why] |
## Tuning Knob Mapping
Maps to GDD Tuning Knob: [knob name and its documented range].
New value is [within / at the edge of / outside] the documented range.
[If outside: explain why the range should be extended.]
## Acceptance Criteria
- [ ] [Parameter] reads [new value] from `assets/data/[file]`
- [ ] Behavior difference is observable in [specific context]
- [ ] No regression in [related behavior]
```
### For Tweak and Addition changes
```markdown
# Quick Design Spec: [Title]
**Type**: [Tweak / Addition]
**System**: [System name]
**GDD Reference**: `design/gdd/[filename].md`
**Date**: [today]
## Change Summary
[1-2 sentences describing what changes and why.]
## Motivation
[Why is this change needed? What player experience problem does it solve?
Reference the relevant MDA aesthetic or player feedback if applicable.]
## Design Delta
Current GDD says (quoting `design/gdd/[filename].md`, [section]):
> [exact quote of the relevant rule or description]
This spec changes that to:
[New rule or description, written with the same precision as a GDD Detailed
Rules section. A programmer should be able to implement from this text alone.]
## New Rules / Values
[Full unambiguous statement of the replacement content. If this introduces
new states, list them. If it introduces new parameters, define their ranges.]
## Affected Systems
| System | Impact | Action Required |
|--------|--------|-----------------|
| [system] | [how it is affected] | [update GDD / update data file / no action] |
## Acceptance Criteria
- [ ] [Specific, testable criterion 1]
- [ ] [Specific, testable criterion 2]
- [ ] [Specific, testable criterion 3]
- [ ] No regression: [the original behavior this must not break]
## GDD Update Required?
[Yes / No]
[If yes: which file, which section, and what the update should say.]
```
### For New Small System changes
Use a trimmed GDD structure. Include only the sections that are directly
necessary — skip Player Fantasy, full Formulas, and Edge Cases unless the
system specifically requires them.
```markdown
# Quick Design Spec: [Title]
**Type**: New Small System
**Scope**: [1-2 sentence description of what this system does and doesn't do]
**Date**: [today]
**Estimated Implementation**: [hours]
## Overview
[One paragraph a new team member could understand. What does this system do,
when does it activate, and what does it produce?]
## Core Rules
[Unambiguous rules for the system. Use numbered lists for sequential behavior
and bullet lists for conditions. Be precise enough that a programmer can
implement without asking questions.]
## Tuning Knobs
| Knob | Default | Range | Category | Rationale |
|------|---------|-------|----------|-----------|
| [name] | [value] | [min–max] | [feel/curve/gate] | [why this default] |
All values must live in `assets/data/[appropriate-file].json`, not hardcoded.
## Acceptance Criteria
- [ ] [Functional criterion: does the right thing]
- [ ] [Functional criterion: handles the edge case]
- [ ] [Experiential criterion: feels right — what a playtest validates]
- [ ] [Regression criterion: does not break adjacent system]
## Systems Index
This system is not currently in `design/gdd/systems-index.md`.
[If it should be added: suggest which layer and priority tier.]
[If it is too small to track: state "This system is below systems-index
tracking threshold — quick spec is sufficient."]
```
---
## 4. Approval and Filing
Present the draft to the user in full. Then ask:
"May I write this Quick Design Spec to
`design/quick-specs/[kebab-case-title]-[YYYY-MM-DD].md`?"
Use today's date in the filename. The title should be a kebab-case description
of the change (e.g., `jump-height-tuning-2026-03-10`,
`parry-window-addition-2026-03-10`).
If yes, create the `design/quick-specs/` directory if it does not exist, then
write the file.
If a GDD update is required (flagged in the spec), ask separately after
writing the quick spec:
"This spec modifies rules in [System Name]. May I update
`design/gdd/[filename].md` — specifically the [section name] section?"
Show the exact text that would be changed (old vs. new) before asking. Do not
make GDD edits without explicit approval.
---
## 5. Handoff
After writing the file, output:
```
Quick Design Spec written to: design/quick-specs/[filename].md
Type: [Tuning / Tweak / Addition / New Small System]
System: [system name]
GDD update: [Required — pending approval / Applied / Not required]
Next step: This spec is ready for `/story-readiness` validation before
implementation. Reference this spec in the story's GDD Reference field.
```
### Pipeline Notes
Quick Design Specs **bypass** `/design-review` and `/review-all-gdds` by
design. They are for small, low-risk, well-scoped changes where the cost of
the full review pipeline exceeds the risk of the change itself.
Redirect to the full pipeline if any of the following are true:
- The change adds a new system that belongs in the systems index
- The change significantly alters cross-system behavior or a system's
contracts with other systems
- The change introduces new player-facing mechanics that affect the
game's MDA aesthetic balance
- Implementation is likely to exceed one week of work
In those cases: "This change has grown beyond quick-spec scope. I recommend
using `/design-system` to author a full GDD for this."

440
.claude/skills/review-all-gdds/SKILL.md Normal file
View file

@ -0,0 +1,440 @@
---
name: review-all-gdds
description: "Holistic cross-GDD consistency and game design review. Reads all system GDDs simultaneously and checks for contradictions between them, stale references, ownership conflicts, formula incompatibilities, and game design theory violations (dominant strategies, economic imbalance, cognitive overload, pillar drift). Run after all MVP GDDs are written, before architecture begins."
argument-hint: "[focus: full | consistency | design-theory | since-last-review]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Bash
context: fork
agent: game-designer
---
# Review All GDDs
This skill reads every system GDD simultaneously and performs two complementary
reviews that cannot be done per-GDD in isolation:
1. **Cross-GDD Consistency** — contradictions, stale references, and ownership
conflicts between documents
2. **Game Design Holism** — issues that only emerge when you see all systems
together: dominant strategies, broken economies, cognitive overload, pillar
drift, competing progression loops
**This is distinct from `/design-review`**, which reviews one GDD for internal
completeness. This skill reviews the *relationships* between all GDDs.
**When to run:**
- After all MVP-tier GDDs are individually approved
- After any GDD is significantly revised mid-production
- Before `/create-architecture` begins (architecture built on inconsistent GDDs
inherits those inconsistencies)
**Argument modes:**
- **No argument / `full`**: Both consistency and design theory passes
- **`consistency`**: Cross-GDD consistency checks only (faster)
- **`design-theory`**: Game design holism checks only
- **`since-last-review`**: Only GDDs modified since the last review report (git-based)
---
## Phase 1: Load Everything
Read all design documents before any analysis:
1. `design/gdd/game-concept.md` — game vision, core loop, MVP definition
2. `design/gdd/game-pillars.md` if it exists — design pillars and anti-pillars
3. `design/gdd/systems-index.md` — authoritative system list, layers, dependencies, status
4. **Every system GDD in `design/gdd/`** — read completely (skip game-concept.md
and systems-index.md — those are read above)
For `since-last-review` mode: run `git log --name-only` to identify GDDs
modified since the last review report file was written. Only load those GDDs
plus any GDDs they depend on.
Report: "Loaded [N] system GDDs covering [M] systems. Pillars: [list]. Anti-pillars: [list]."
If fewer than 2 system GDDs exist, stop:
> "Cross-GDD review requires at least 2 system GDDs. Write more GDDs first,
> then re-run `/review-all-gdds`."
---
## Phase 2: Cross-GDD Consistency
Work through every pair and group of GDDs to find contradictions and gaps.
### 2a: Dependency Bidirectionality
For every GDD's Dependencies section, check that every listed dependency is
reciprocal:
- If GDD-A lists "depends on GDD-B", check that GDD-B lists GDD-A as a dependent
- If GDD-A lists "depended on by GDD-C", check that GDD-C lists GDD-A as a dependency
- Flag any one-directional dependency as a consistency issue
```
⚠️ Dependency Asymmetry
combat.md lists: Depends On → health-system.md
health-system.md does NOT list combat.md as a dependent
→ One of these documents has a stale dependency section
```
### 2b: Rule Contradictions
For each game rule, mechanic, or constraint defined in any GDD, check whether
any other GDD defines a contradicting rule for the same situation:
Categories to scan:
- **Health and damage**: Does any GDD say damage floor is 1? Does any other say
armour can reduce damage to 0? These contradict.
- **Resource ownership**: If two GDDs both define how a shared resource (gold,
stamina, mana) accumulates or depletes, do they agree?
- **State transitions**: If GDD-A describes what happens when a character dies,
does GDD-B's description of the same event agree?
- **Timing**: If GDD-A says "X happens on the same frame", does GDD-B assume
it happens asynchronously?
- **Stacking rules**: If GDD-A says status effects stack, does GDD-B assume
they don't?
```
🔴 Rule Contradiction
combat.md: "Minimum damage after armour reduction is 1"
status-effects.md: "Poison ignores armour and can reduce health by any amount,
including to 0"
→ These rules directly contradict. Which GDD is authoritative?
```
### 2c: Stale References
For every cross-document reference (GDD-A mentions a mechanic, value, or
system name from GDD-B), verify the referenced element still exists in GDD-B
with the same name and behaviour:
- If GDD-A says "combo multiplier from the combat system feeds into score", check
that the combat GDD actually defines a combo multiplier that outputs to score
- If GDD-A references "the XP curve defined in progression.md", check that
progression.md actually has an XP curve, not a flat-level system
- If GDD-A was written before GDD-B and assumed a mechanic that GDD-B later
designed differently, flag GDD-A as containing a stale reference
```
⚠️ Stale Reference
inventory.md (written first): "Item weight uses the encumbrance formula
from movement.md"
movement.md (written later): Defines no encumbrance formula — uses a flat
carry limit instead
→ inventory.md references a formula that doesn't exist
```
### 2d: Data and Tuning Knob Ownership Conflicts
Two GDDs should not both claim to own the same data or tuning knob. Scan all
Tuning Knobs sections across all GDDs and flag duplicates:
```
⚠️ Ownership Conflict
combat.md Tuning Knobs: "base_damage_multiplier — controls damage scaling"
progression.md Tuning Knobs: "damage_multiplier — scales with player level"
→ Two GDDs define multipliers on the same output. Which owns the final value?
This will produce either a double-application bug or a design conflict.
```
### 2e: Formula Compatibility
For GDDs whose formulas are connected (output of one feeds input of another),
check that the output range of the upstream formula is within the expected
input range of the downstream formula:
- If combat.md outputs damage values between 1–500, and the health system is
designed for health values between 10–100, a one-hit kill is almost always
possible — is that intended?
- If the economy GDD expects item prices between 1–1000 gold, and the
progression GDD generates gold at a rate of 50–5000 per session, the
economy will either be trivially easy or permanently locked — is that intended?
Flag incompatibilities as CONCERNS (design judgment needed, not necessarily wrong):
```
⚠️ Formula Range Mismatch
combat.md: Max damage output = 500 (at max level, max gear)
health-system.md: Base player health = 100, max health = 250
→ Late-game combat can one-shot a max-health player in a single hit.
Is this intentional? If not, either damage ceiling or health ceiling needs adjustment.
```
### 2f: Acceptance Criteria Cross-Check
Scan Acceptance Criteria sections across all GDDs for contradictions:
- GDD-A criteria: "Player cannot die from a single hit"
- GDD-B criteria: "Boss attack deals 150% of player max health"
These acceptance criteria cannot both pass simultaneously.
---
## Phase 3: Game Design Holism
Review all GDDs together through the lens of game design theory and player
psychology. These are issues that individual GDD reviews cannot catch because
they require seeing all systems at once.
### 3a: Progression Loop Competition
A game should have one dominant progression loop that players feel is "the
point" of the game, with supporting loops that feed into it. When multiple
systems compete equally as the primary progression driver, players don't know
what the game is about.
Scan all GDDs for systems that:
- Award the player's primary resource (XP, levels, prestige, unlocks)
- Define themselves as the "core" or "main" loop
- Have comparable depth and time investment to other systems doing the same
```
⚠️ Competing Progression Loops
combat.md: Awards XP, unlocks abilities, is described as "the core loop"
crafting.md: Awards XP, unlocks recipes, is described as "the primary activity"
exploration.md: Awards XP, unlocks map areas, described as "the main driver"
→ Three systems all claim to be the primary progression loop and all award
the same primary currency. Players will optimise one and ignore the others.
Consider: one primary loop with the others as support systems.
```
### 3b: Player Attention Budget
Count how many systems require active player attention simultaneously during
a typical session. Each actively-managed system costs attention:
- Active = player must make decisions about this system regularly during play
- Passive = system runs automatically, player sees results but doesn't manage it
More than 3-4 simultaneously active systems creates cognitive overload for most
players. Present the count and flag if it exceeds 4 concurrent active systems:
```
⚠️ Cognitive Load Risk
Simultaneously active systems during combat:
1. combat.md — combat decisions (active)
2. stamina-system.md — stamina management (active)
3. status-effects.md — status tracking (active)
4. inventory.md — mid-combat item use (active)
5. ability-system.md — ability cooldown management (active)
6. companion-ai.md — companion command decisions (active)
→ 6 simultaneously active systems during the core loop.
Research suggests 3-4 is the comfortable limit for most players.
Consider: which of these can be made passive or simplified?
```
### 3c: Dominant Strategy Detection
A dominant strategy makes other strategies irrelevant — players discover it,
use it exclusively, and find the rest of the game boring. Look for:
- **Resource monopolies**: One strategy generates a resource significantly
faster than all others
- **Risk-free power**: A strategy that is both high-reward and low-risk
(if high-risk strategies exist, they need proportionally higher reward)
- **No trade-offs**: An option that is superior in all dimensions to all others
- **Obvious optimal path**: If any progression choice is "clearly correct",
the others aren't real choices
```
⚠️ Potential Dominant Strategy
combat.md: Ranged attacks deal 80% of melee damage with no risk
combat.md: Melee attacks deal 100% damage but require close range
→ Unless melee has a significant compensating advantage (AOE, stagger,
resource regeneration), ranged is dominant — higher safety, only 20% less
damage. Consider what melee offers that ranged cannot.
```
### 3d: Economic Loop Analysis
Identify all resources across all GDDs (gold, XP, crafting materials, stamina,
health, mana, etc.). For each resource, map its **sources** (how players gain
it) and **sinks** (how players spend it).
Flag dangerous economic conditions:
| Condition | Sign | Risk |
|-----------|------|------|
| **Infinite source, no sink** | Resource accumulates indefinitely | Late game becomes trivially easy |
| **Sink, no source** | Resource drains to zero | System becomes unavailable |
| **Source >> Sink** | Surplus accumulates | Resource becomes meaningless |
| **Sink >> Source** | Constant scarcity | Frustration and gatekeeping |
| **Positive feedback loop** | More resource → easier to earn more | Runaway leader, snowball |
| **No catch-up** | Falling behind accelerates deficit | Unrecoverable states |
```
🔴 Economic Imbalance: Unbounded Positive Feedback
gold economy:
Sources: monster drops (scales with player power), merchant selling (unlimited)
Sinks: equipment purchase (one-time), ability upgrades (finite count)
→ After equipment and abilities are purchased, gold has no sink.
Infinite surplus. Gold becomes meaningless mid-game.
Add ongoing gold sinks (upkeep, consumables, cosmetics, gambling).
```
### 3e: Difficulty Curve Consistency
When multiple systems scale with player progression, they must scale in
compatible directions and at compatible rates. Mismatched scaling curves
create unintended difficulty spikes or trivialisations.
For each system that scales over time, extract:
- What scales (enemy health, player damage, resource cost, area size)
- How it scales (linear, exponential, stepped)
- When it scales (level, time, area)
Compare all scaling curves. Flag mismatches:
```
⚠️ Difficulty Curve Mismatch
combat.md: Enemy health scales exponentially with area (×2 per area)
progression.md: Player damage scales linearly with level (+10% per level)
→ By area 5, enemies have 32× base health; player deals ~1.5× base damage.
The gap widens indefinitely. Late areas will become inaccessibly difficult
unless the curves are reconciled.
```
### 3f: Pillar Alignment
Every system should clearly serve at least one design pillar. A system that
serves no pillar is "scope creep by design" — it's in the game but not in
service of what the game is trying to be.
For each GDD system, check its Player Fantasy section against the design pillars.
Flag any system whose stated fantasy doesn't map to any pillar:
```
⚠️ Pillar Drift
fishing-system.md: Player Fantasy — "peaceful, meditative activity"
Pillars: "Brutal Combat", "Tense Survival", "Emergent Stories"
→ The fishing system serves none of the three pillars. Either add a pillar
that covers it, redesign it to serve an existing pillar, or cut it.
```
Also check anti-pillars — flag any system that does what an anti-pillar
explicitly says the game will NOT do:
```
🔴 Anti-Pillar Violation
Anti-Pillar: "We will NOT have linear story progression — player defines their path"
main-quest.md: Defines a 12-chapter linear story with mandatory sequence
→ This system directly violates the defined anti-pillar.
```
### 3g: Player Fantasy Coherence
The player fantasies across all systems should be compatible — they should
reinforce a consistent identity for what the player IS in this game. Conflicting
player fantasies create identity confusion.
```
⚠️ Player Fantasy Conflict
combat.md: "You are a ruthless, precise warrior — every kill is earned"
dialogue.md: "You are a charismatic diplomat — violence is always avoidable"
exploration.md: "You are a reckless adventurer — diving in without a plan"
→ Three systems present incompatible identities. Players will feel the game
doesn't know what it wants them to be. Consider: do these fantasies serve
the same core identity from different angles, or do they genuinely conflict?
```
---
## Phase 4: Output the Review Report
```
## Cross-GDD Review Report
Date: [date]
GDDs Reviewed: [N]
Systems Covered: [list]
---
### Consistency Issues
#### Blocking (must resolve before architecture begins)
🔴 [Issue title]
[What GDDs are involved, what the contradiction is, what needs to change]
#### Warnings (should resolve, but won't block)
⚠️ [Issue title]
[What GDDs are involved, what the concern is]
---
### Game Design Issues
#### Blocking
🔴 [Issue title]
[What the problem is, which GDDs are involved, design recommendation]
#### Warnings
⚠️ [Issue title]
[What the concern is, which GDDs are affected, recommendation]
---
### GDDs Flagged for Revision
| GDD | Reason | Type | Priority |
|-----|--------|------|----------|
| combat.md | Rule contradiction with status-effects.md | Consistency | Blocking |
| inventory.md | Stale reference to nonexistent formula | Consistency | Blocking |
| fishing.md | No pillar alignment | Design Theory | Warning |
---
### Verdict: [PASS / CONCERNS / FAIL]
PASS: No blocking issues. Warnings present but don't prevent architecture.
CONCERNS: Warnings present that should be resolved but are not blocking.
FAIL: One or more blocking issues must be resolved before architecture begins.
### If FAIL — required actions before re-running:
[Specific list of what must change in which GDD]
```
---
## Phase 5: Write Report and Flag GDDs
Ask: "May I write this review to `design/gdd/gdd-cross-review-[date].md`?"
If any GDDs are flagged for revision:
Ask: "Should I update the systems index to mark these GDDs as needing revision?"
- If yes: for each flagged GDD, update its Status field in systems-index.md
to "Needs Revision (Cross-GDD Review)" with a short note on why.
Ask approval before writing.
---
## Phase 6: Handoff
After the report is written:
- **If FAIL**: "Resolve the blocking issues in the flagged GDDs, then re-run
`/review-all-gdds` to confirm they're cleared before starting architecture."
- **If CONCERNS**: "Warnings are present but not blocking. You may proceed to
`/create-architecture` and resolve warnings in parallel, or resolve them now
for a cleaner baseline."
- **If PASS**: "GDDs are internally consistent. Run `/create-architecture` to
begin translating the design into an engine-aware technical blueprint."
Gate reminder: `/gate-check technical-setup` now requires a PASS or CONCERNS
verdict from this review before architecture work can begin.
---
## Collaborative Protocol
1. **Read silently** — load all GDDs before presenting anything
2. **Show everything** — present the full consistency and design theory analysis
before asking for any action
3. **Distinguish blocking from advisory** — not every issue needs to block
architecture; be clear about which do
4. **Don't make design decisions** — flag contradictions and options, but never
unilaterally decide which GDD is "right"
5. **Ask before writing** — confirm before writing the report or updating the
systems index
6. **Be specific** — every issue must cite the exact GDD, section, and text
involved; no vague warnings

167
.claude/skills/sprint-status/SKILL.md Normal file
View file

@ -0,0 +1,167 @@
---
name: sprint-status
description: "Fast sprint status check. Reads the current sprint plan, scans story files for status, and produces a concise progress snapshot with burndown assessment and emerging risks. Run at any time during a sprint for quick situational awareness."
argument-hint: "[sprint-number or blank for current]"
user-invocable: true
allowed-tools: Read, Glob, Grep
---
# Sprint Status
This is a fast situational awareness check, not a sprint review. It reads the
current sprint plan and story files, scans for status markers, and produces a
concise snapshot in under 30 lines. For detailed sprint management, use
`/sprint-plan update` or `/milestone-review`.
**This skill is read-only.** It never proposes changes, never asks to write
files, and makes at most one concrete recommendation.
---
## 1. Find the Sprint
- If an argument is given (e.g., `/sprint-status 3`), search
`production/sprints/` for a file matching `sprint-03.md`, `sprint-3.md`,
or similar. Report which file was found.
- If no argument is given, find the most recently modified file in
`production/sprints/` and treat it as the current sprint.
- If `production/sprints/` does not exist or is empty, report: "No sprint
files found. Start a sprint with `/sprint-plan new`." Then stop.
Read the sprint file in full. Extract:
- Sprint number and goal
- Start date and end date
- All story or task entries with their priority (Must Have / Should Have /
Nice to Have), owner, and estimate
---
## 2. Calculate Days Remaining
Using today's date and the sprint end date from the sprint file, calculate:
- Total sprint days (end minus start)
- Days elapsed
- Days remaining
- Percentage of time consumed
If the sprint file does not include explicit dates, note "Sprint dates not
found — burndown assessment skipped."
---
## 3. Scan Story Status
For each story or task referenced in the sprint plan:
1. If the entry references a story file path, check if the file exists.
Read the file and scan for status markers: DONE, COMPLETE, IN PROGRESS,
BLOCKED, NOT STARTED (case-insensitive).
2. If the entry has no file path (inline task in the sprint plan), scan the
sprint plan itself for status markers next to that entry.
3. If no status marker is found, classify as NOT STARTED.
4. If a file is referenced but does not exist, classify as MISSING and note it.
Optionally (fast check only — do not do a deep scan): grep `src/` for a
directory or file name that matches the story's system slug to check for
implementation evidence. This is a hint only, not a definitive status.
---
## 4. Burndown Assessment
Calculate:
- Tasks complete (DONE or COMPLETE)
- Tasks in progress (IN PROGRESS)
- Tasks blocked (BLOCKED)
- Tasks not started (NOT STARTED or MISSING)
- Completion percentage: (complete / total) * 100
Assess burndown by comparing completion percentage to time consumed percentage:
- **On Track**: completion % is within 10 points of time consumed % or ahead
- **At Risk**: completion % is 10-25 points behind time consumed %
- **Behind**: completion % is more than 25 points behind time consumed %
If dates are unavailable, skip the burndown assessment and report "On Track /
At Risk / Behind: unknown — sprint dates not found."
---
## 5. Output
Keep the total output to 30 lines or fewer. Use this format:
```markdown
## Sprint [N] Status — [Today's Date]
**Sprint Goal**: [from sprint plan]
**Days Remaining**: [N] of [total] ([% time consumed])
### Progress: [complete/total] tasks ([%])
| Story / Task | Priority | Status | Owner | Blocker |
|----------------------|------------|-------------|---------|----------------|
| [title] | Must Have | DONE | [owner] | |
| [title] | Must Have | IN PROGRESS | [owner] | |
| [title] | Must Have | BLOCKED | [owner] | [brief reason] |
| [title] | Should Have| NOT STARTED | [owner] | |
### Burndown: [On Track / At Risk / Behind]
[1-2 sentences. If behind: which Must Haves are at risk. If on track: confirm
and note any Should Haves the team could pull.]
### Must-Haves at Risk
[List any Must Have stories that are BLOCKED or NOT STARTED with less than
40% of sprint time remaining. If none, write "None."]
### Emerging Risks
[Any risks visible from the story scan: missing files, cascading blockers,
stories with no owner. If none, write "None identified."]
### Recommendation
[One concrete action, or "Sprint is on track — no action needed."]
```
---
## 6. Fast Escalation Rules
Apply these rules before outputting, and place the flag at the TOP of the
output if triggered (above the status table):
**Critical flag** — if Must Have stories are BLOCKED or NOT STARTED and
less than 40% of the sprint time remains:
```
SPRINT AT RISK: [N] Must Have stories are not complete with [X]% of sprint
time remaining. Recommend replanning with `/sprint-plan update`.
```
**Completion flag** — if all Must Have stories are DONE:
```
All Must Haves complete. Team can pull from Should Have backlog.
```
**Missing stories flag** — if any referenced story files do not exist:
```
NOTE: [N] story files referenced in the sprint plan are missing.
Run `/story-readiness sprint` to validate story file coverage.
```
---
## Collaborative Protocol
This skill is read-only. It reports observed facts from files on disk.
- It does not update the sprint plan
- It does not change story status
- It does not propose scope cuts (that is `/sprint-plan update`)
- It makes at most one recommendation per run
For more detail on a specific story, the user can read the story file directly
or run `/story-readiness [path]`.
For sprint replanning, use `/sprint-plan update`.
For end-of-sprint retrospective, use `/milestone-review`.

248
.claude/skills/story-done/SKILL.md Normal file
View file

@ -0,0 +1,248 @@
---
name: story-done
description: "End-of-story completion review. Reads the story file, verifies each acceptance criterion against the implementation, checks for GDD/ADR deviations, prompts code review, updates story status to Complete, and surfaces the next ready story from the sprint."
argument-hint: "[story-file-path]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Bash, Edit
---
# Story Done
This skill closes the loop between design and implementation. Run it at the end
of implementing any story. It ensures every acceptance criterion is verified
before the story is marked done, GDD and ADR deviations are explicitly
documented rather than silently introduced, code review is prompted rather than
forgotten, and the story file reflects actual completion status.
**Output:** Updated story file (Status: Complete) + surfaced next story.
---
## Phase 1: Find the Story
**If a file path is provided** (e.g., `/story-done production/epics/core/story-damage-calculator.md`):
read that file directly.
**If no argument is provided:**
1. Check `production/session-state/active.md` for the currently active story.
2. If not found there, read the most recent file in `production/sprints/` and
look for stories marked IN PROGRESS.
3. If multiple in-progress stories are found, use `AskUserQuestion`:
- "Which story are we completing?"
- Options: list the in-progress story file names.
4. If no story can be found, ask the user to provide the path.
---
## Phase 2: Read the Story
Read the full story file. Extract and hold in context:
- **Story name and ID**
- **GDD Requirement ID(s)** referenced
- **ADR reference(s)** referenced
- **Acceptance Criteria** — the complete list (every checkbox item)
- **Implementation files** — files listed under "files to create/modify"
- **Engine notes** — any engine-specific constraints noted
- **Definition of Done** — if present, the story-level DoD
- **Estimated vs actual scope** — if an estimate was noted
Also read:
- The referenced GDD section — just the acceptance criteria and key rules, not
the full document
- The referenced ADR(s) — just the Decision and Consequences sections
---
## Phase 3: Verify Acceptance Criteria
For each acceptance criterion in the story, attempt verification using one of
three methods:
### Automatic verification (run without asking)
- **File existence check**: `Glob` for files the story said would be created.
- **Test pass check**: if a test file path is mentioned, run it via `Bash`.
- **No hardcoded values check**: `Grep` for numeric literals in gameplay code
paths that should be in config files.
- **No hardcoded strings check**: `Grep` for player-facing strings in `src/`
that should be in localization files.
- **Dependency check**: if a criterion says "depends on X", check that X exists.
### Manual verification with confirmation (use `AskUserQuestion`)
- Criteria about subjective qualities ("feels responsive", "animations play correctly")
- Criteria about gameplay behaviour ("player takes damage when...", "enemy responds to...")
- Performance criteria ("completes within Xms") — ask if profiled or accept as assumed
Batch up to 4 manual verification questions into a single `AskUserQuestion` call:
```
question: "Does [criterion]?"
options: "Yes — passes", "No — fails", "Not tested yet"
```
### Unverifiable (flag without blocking)
- Criteria that require a full game build to test (end-to-end gameplay scenarios)
- Mark as: `DEFERRED — requires playtest session`
---
## Phase 4: Check for Deviations
Compare the implementation against the design documents.
Run these checks automatically:
1. **GDD rules check**: Read the GDD section referenced in the story. `Grep` the
implemented files for key function names, data structures, or class names
mentioned in the GDD. If the GDD specifies a formula, check for recognizable
variable names from that formula.
2. **ADR constraints check**: Read the referenced ADR's Decision section. Check
for forbidden patterns from `docs/architecture/control-manifest.md` (if it
exists). `Grep` for patterns explicitly forbidden in the ADR.
3. **Hardcoded values check**: `Grep` the implemented files for numeric literals
in gameplay logic that should be in data files.
4. **Scope check**: Did the implementation touch files outside the story's stated
scope? (files not listed in "files to create/modify")
For each deviation found, categorize:
- **BLOCKING** — implementation contradicts the GDD or ADR (must fix before
marking complete)
- **ADVISORY** — implementation drifts slightly from spec but is functionally
equivalent (document, user decides)
- **OUT OF SCOPE** — additional files were touched beyond the story's stated
boundary (flag for awareness — may be valid or scope creep)
---
## Phase 5: Code Review Prompt
After criteria verification and deviation check, use `AskUserQuestion`:
```
question: "Implementation verified. Run /code-review on the changed files?"
options:
- "Yes — run /code-review now"
- "Skip — I'll review manually"
- "Skip — already reviewed"
```
If "Yes": list the files to review and say:
"Run `/code-review [file1] [file2]` to review the implementation before
marking complete."
Do not run code-review inline — surface it and let the developer decide when
to invoke it.
---
## Phase 6: Present the Completion Report
Before updating any files, present the full report:
```markdown
## Story Done: [Story Name]
**Story**: [file path]
**Date**: [today]
### Acceptance Criteria: [X/Y passing]
- [x] [Criterion 1] — auto-verified (test passes)
- [x] [Criterion 2] — confirmed
- [ ] [Criterion 3] — FAILS: [reason]
- [?] [Criterion 4] — DEFERRED: requires playtest
### Deviations
[NONE] OR:
- BLOCKING: [description] — [GDD/ADR reference]
- ADVISORY: [description] — user accepted / flagged for tech debt
### Scope
[All changes within stated scope] OR:
- Extra files touched: [list] — [note whether valid or scope creep]
### Verdict: COMPLETE / COMPLETE WITH NOTES / BLOCKED
```
**Verdict definitions:**
- **COMPLETE**: all criteria pass, no blocking deviations
- **COMPLETE WITH NOTES**: all criteria pass, advisory deviations documented
- **BLOCKED**: failing criteria or blocking deviations must be resolved first
If the verdict is **BLOCKED**: do not proceed to Phase 7. List what must be
fixed. Offer to help fix the blocking items.
---
## Phase 7: Update Story Status
Ask before writing: "May I update the story file to mark it Complete and log
the completion notes?"
If yes, edit the story file:
1. Update the status field: `Status: Complete`
2. Add a `## Completion Notes` section at the bottom:
```markdown
## Completion Notes
**Completed**: [date]
**Criteria**: [X/Y passing] ([any deferred items listed])
**Deviations**: [None] or [list of advisory deviations]
**Code Review**: [Pending / Complete / Skipped]
```
3. If advisory deviations exist, ask: "Should I log these as tech debt in
`docs/tech-debt-register.md`?"
---
## Phase 8: Surface the Next Story
After completion, help the developer keep momentum:
1. Read the current sprint plan from `production/sprints/`.
2. Find stories that are:
- Status: READY or NOT STARTED
- Not blocked by other incomplete stories
- In the Must Have or Should Have tier
Present:
```
### Next Up
The following stories are ready to pick up:
1. [Story name] — [1-line description] — Est: [X hrs]
2. [Story name] — [1-line description] — Est: [X hrs]
Run `/story-readiness [path]` to confirm a story is implementation-ready
before starting.
```
If no more stories are ready in this sprint:
"No more stories ready in this sprint. Consider running `/sprint-status` to
assess sprint health."
If all Must Have stories are complete:
"All Must Have stories are complete. Consider running `/milestone-review` or
pulling from the Should Have list."
---
## Collaborative Protocol
- **Never mark a story complete without user approval** — Phase 7 requires an
explicit "yes" before any file is edited.
- **Never auto-fix failing criteria** — report them and ask what to do.
- **Deviations are facts, not judgments** — present them neutrally; the user
decides if they are acceptable.
- **BLOCKED verdict is advisory** — the user can override and mark complete
anyway; document the risk explicitly if they do.
- Use `AskUserQuestion` for the code review prompt and for batching manual
criteria confirmations.

222
.claude/skills/story-readiness/SKILL.md Normal file
View file

@ -0,0 +1,222 @@
---
name: story-readiness
description: "Validate that a story file is implementation-ready. Checks for embedded GDD requirements, ADR references, engine notes, clear acceptance criteria, and no open design questions. Produces READY / NEEDS WORK / BLOCKED verdict with specific gaps."
argument-hint: "[story-file-path or 'all' or 'sprint']"
user-invocable: true
allowed-tools: Read, Glob, Grep
context: fork
---
# Story Readiness
This skill validates that a story file contains everything a developer needs
to begin implementation — no mid-sprint design interruptions, no guessing,
no ambiguous acceptance criteria. Run it before assigning a story.
**This skill is read-only.** It never edits story files. It reports findings
and asks whether the user wants help filling gaps.
**Output:** Verdict per story (READY / NEEDS WORK / BLOCKED) with a specific
gap list for each non-ready story.
---
## 1. Parse Arguments
- **Specific path** (e.g., `/story-readiness production/epics/combat/story-001-basic-attack.md`):
validate that single story file.
- **`sprint`**: read the current sprint plan from `production/sprints/` (most
recent file), extract every story path it references, validate each one.
- **`all`**: glob `production/epics/**/*.md`, exclude `EPIC.md` index files,
validate every story file found.
- **No argument**: ask the user which scope to validate.
If no argument is given, use `AskUserQuestion`:
- "What would you like to validate?"
- Options: "A specific story file", "All stories in the current sprint",
"All stories in production/epics/", "Stories for a specific epic"
Report the scope before proceeding: "Validating [N] story files."
---
## 2. Load Supporting Context
Before checking any stories, load reference documents once (not per-story):
- `design/gdd/systems-index.md` — to know which systems have approved GDDs
- `docs/architecture/control-manifest.md` — to know which manifest rules exist
(if the file does not exist, note it as missing once; do not re-flag per story)
- The current sprint file (if scope is `sprint`) — to identify Must Have /
Should Have priority for escalation decisions
---
## 3. Story Readiness Checklist
For each story file, evaluate every item below. A story is READY only if all
items pass or are explicitly marked N/A with a stated reason.
### Design Completeness
- [ ] **GDD requirement referenced**: The story includes a `design/gdd/` path
and quotes or links a specific requirement, acceptance criterion, or rule from
that GDD — not just the GDD filename. A link to the document without tracing
to a specific requirement does not pass.
- [ ] **Requirement is self-contained**: The acceptance criteria in the story
are understandable without opening the GDD. A developer should not need to
read a separate document to understand what DONE means.
- [ ] **Acceptance criteria are testable**: Each criterion is a specific,
observable condition — not "implement X" or "the system works correctly".
Bad example: "Implement the jump mechanic." Good example: "Jump reaches
max height of 5 units within 0.3 seconds when jump is held."
- [ ] **No acceptance criteria require judgment calls**: Criteria like
"feels responsive" or "looks good" are not testable without a defined
benchmark. These must be replaced with specific observable conditions or
playtest protocols.
### Architecture Completeness
- [ ] **ADR referenced or N/A stated**: The story references at least one
Accepted ADR, OR explicitly states "No ADR applies" with a brief reason.
A story with no ADR reference and no explicit N/A note fails this check.
- [ ] **Engine notes present**: For any post-cutoff engine API this story
is likely to touch, implementation notes or a verification requirement are
included. If the story clearly does not touch engine APIs (e.g., it is a
pure data/config change), "N/A — no engine API involved" is acceptable.
- [ ] **Control manifest rules noted**: Relevant layer rules from the control
manifest are referenced, OR "N/A — manifest not yet created" is stated.
This item auto-passes if `docs/architecture/control-manifest.md` does not
exist yet (do not penalize stories written before the manifest was created).
### Scope Clarity
- [ ] **Estimate present**: The story includes a size estimate (hours,
points, or a t-shirt size). A story with no estimate cannot be planned.
- [ ] **In-scope / Out-of-scope boundary stated**: The story states what
it does NOT include, either in an explicit Out of Scope section or in
language that makes the boundary unambiguous. Without this, scope creep
during implementation is likely.
- [ ] **Story dependencies listed**: If this story depends on other stories
being DONE first, those story IDs are listed. If there are no dependencies,
"None" is explicitly stated (not just omitted).
### Open Questions
- [ ] **No unresolved design questions**: The story does not contain text
flagged as "UNRESOLVED", "TBD", "TODO", "?", or equivalent markers in
any acceptance criterion, implementation note, or rule statement.
- [ ] **Dependency stories are not in DRAFT**: For each story listed as a
dependency, check if the file exists and does not have a DRAFT status. A
story that depends on a DRAFT or missing story is BLOCKED, not just
NEEDS WORK.
### Definition of Done
- [ ] **At least 3 testable acceptance criteria**: Fewer than 3 suggests
the story is either trivially small (should it be a story?) or under-specified.
- [ ] **Performance budget noted if applicable**: If this story touches any
part of the gameplay loop, rendering, or physics, a performance budget or
a "no performance impact expected — [reason]" note is present.
- [ ] **Test strategy noted**: The story states whether verification is by
unit test, manual test, or playtest. "Acceptance criteria verified by
[test type]" is sufficient.
---
## 4. Verdict Assignment
Assign one of three verdicts per story:
**READY** — All checklist items pass or have explicit N/A justifications.
The story can be assigned immediately.
**NEEDS WORK** — One or more checklist items fail, but all dependency stories
exist and are not DRAFT. The story can be fixed before assignment.
**BLOCKED** — One or more dependency stories are missing or in DRAFT state,
OR a critical design question (flagged UNRESOLVED in a criterion or rule) has
no owner. The story cannot be assigned until the blocker is resolved. Note:
a story that is BLOCKED may also have NEEDS WORK items — list both.
---
## 5. Output Format
### Single story output
```
## Story Readiness: [story title]
File: [path]
Verdict: [READY / NEEDS WORK / BLOCKED]
### Passing Checks (N/[total])
[list passing items briefly]
### Gaps
- [Checklist item]: [exact description of what is missing or wrong]
Fix: [specific text needed to resolve this gap]
### Blockers (if BLOCKED)
- [What is blocking]: [story ID or design question that must resolve first]
```
### Multiple story aggregate output
```
## Story Readiness Summary — [scope] — [date]
Ready: [N] stories
Needs Work: [N] stories
Blocked: [N] stories
### Ready Stories
- [story title] ([path])
### Needs Work
- [story title]: [primary gap — one line]
- [story title]: [primary gap — one line]
### Blocked Stories
- [story title]: Blocked by [story ID / design question]
---
[Full detail for each non-ready story follows, using the single-story format]
```
### Sprint escalation
If the scope is `sprint` and any Must Have stories are NEEDS WORK or BLOCKED,
add a prominent warning at the top of the output:
```
WARNING: [N] Must Have stories are not implementation-ready.
[List them with their primary gap or blocker.]
Resolve these before the sprint begins or replan with `/sprint-plan update`.
```
---
## 6. Collaborative Protocol
This skill is read-only. It never proposes edits or asks to write files.
After reporting findings, offer:
"Would you like help filling in the gaps for any of these stories? I can
draft the missing sections for your approval."
If the user says yes for a specific story, draft only the missing sections
in conversation. Do not use Write or Edit tools — the user (or
`/create-epics-stories`) handles writing.
**Redirect rules:**
- If a story file does not exist at all: "This story file is missing entirely.
Run `/create-epics-stories [system-name]` to generate it from the GDD and ADR."
- If a story has no GDD reference and the work appears small: "This story has
no GDD reference. If the change is small (under ~4 hours), run
`/quick-design [description]` to create a Quick Design Spec, then reference
that spec in the story."
- If a story's scope has grown beyond its original sizing: "This story appears
to have expanded in scope. Consider splitting it or escalating to the producer
before implementation begins."

96
.claude/skills/team-ui/SKILL.md
View file

@ -1,6 +1,6 @@
---
name: team-ui
description: "Orchestrate the UI team: coordinates ux-designer, ui-programmer, and art-director to design, implement, and polish a user interface feature from wireframe to final."
description: "Orchestrate the UI team through the full UX pipeline: from UX spec authoring through visual design, implementation, review, and polish. Integrates with /ux-design, /ux-review, and studio UX templates."
argument-hint: "[UI feature description]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task, AskUserQuestion, TodoWrite
@ -16,6 +16,13 @@ The user must approve before moving to the next phase.
- **ux-designer** — User flows, wireframes, accessibility, input handling
- **ui-programmer** — UI framework, screens, widgets, data binding, implementation
- **art-director** — Visual style, layout polish, consistency with art bible
- **accessibility-specialist** — Audits accessibility compliance at Phase 4
**Templates used by this pipeline:**
- `ux-spec.md` — Standard screen/flow UX specification
- `hud-design.md` — HUD-specific UX specification
- `interaction-pattern-library.md` — Reusable interaction patterns
- `accessibility-requirements.md` — Committed accessibility tier and requirements
## How to Delegate
@ -23,48 +30,89 @@ Use the Task tool to spawn each team member as a subagent:
- `subagent_type: ux-designer` — User flows, wireframes, accessibility, input handling
- `subagent_type: ui-programmer` — UI framework, screens, widgets, data binding
- `subagent_type: art-director` — Visual style, layout polish, art bible consistency
- `subagent_type: accessibility-specialist` — Accessibility compliance audit
Always provide full context in each agent's prompt (feature requirements, existing UI patterns, platform targets). Launch independent agents in parallel where the pipeline allows it (e.g., Phase 4 review agents can run simultaneously).
## Pipeline
### Phase 1: UX Design
Delegate to **ux-designer**:
- Define the user flow for this feature (entry points, states, exit points)
- Create wireframes for each screen/state
- Specify interaction patterns: how does keyboard/mouse AND gamepad navigate this?
- Define accessibility requirements: text sizes, contrast, colorblind safety
- Identify data the UI needs to display (what game state does it read?)
- Output: UX spec with wireframes and interaction map
### Phase 1a: Context Gathering
Before designing anything, read and synthesize:
- `design/gdd/game-concept.md` — platform targets and intended audience
- `design/player-journey.md` — player's state and context when they reach this screen
- All GDD UI Requirements sections relevant to this feature
- `design/ux/interaction-patterns.md` — existing patterns to reuse (not reinvent)
- `design/accessibility-requirements.md` — committed accessibility tier (e.g., Basic, Enhanced, Full)
Summarize the context in a brief for the ux-designer: what the player is doing, what they need, what constraints apply, and which existing patterns are relevant.
### Phase 1b: UX Spec Authoring
Invoke `/ux-design [feature name]` skill OR delegate directly to ux-designer to produce `design/ux/[feature-name].md` following the `ux-spec.md` template.
If designing the HUD, use the `hud-design.md` template instead of `ux-spec.md`.
> **Notes on special cases:**
> - For HUD design specifically, invoke `/ux-design` with `argument: hud` (e.g., `/ux-design hud`).
> - For the interaction pattern library, run `/ux-design patterns` once at project start and update it whenever new patterns are introduced during later phases.
Output: `design/ux/[feature-name].md` with all required spec sections filled.
### Phase 1c: UX Review
After the spec is complete, invoke `/ux-review design/ux/[feature-name].md`.
**Gate**: Do not proceed to Phase 2 until the verdict is APPROVED. If the verdict is NEEDS REVISION, the ux-designer must address the flagged issues and re-run the review. The user may explicitly accept a NEEDS REVISION risk and proceed, but this must be a conscious decision — present the specific concerns via `AskUserQuestion` before asking whether to proceed.
### Phase 2: Visual Design
Delegate to **art-director**:
- Review wireframes against the art bible
- Define visual treatment: colors, typography, spacing, animations
- Specify asset requirements (icons, backgrounds, decorative elements)
- Ensure consistency with existing UI screens
- Output: visual design spec with style notes
- Review the full UX spec (flows, wireframes, interaction patterns, accessibility notes) — not just the wireframe images
- Apply visual treatment from the art bible: colors, typography, spacing, animation style
- Check that visual design preserves accessibility compliance: verify color contrast ratios, and confirm color is never the only indicator of state (shape, text, or icon must reinforce it)
- Specify all asset requirements needed from the art pipeline: icons at specified sizes, background textures, fonts, decorative elements — with precise dimensions and format requirements
- Ensure consistency with existing implemented UI screens
- Output: visual design spec with style notes and asset manifest
### Phase 3: Implementation
Delegate to **ui-programmer**:
- Implement the UI following the UX spec and visual design
- Ensure UI NEVER owns or modifies game state — display only, events for actions
- All text through localization system — no hardcoded strings
- Support both input methods (keyboard/mouse + gamepad)
- Implement accessibility features (text scaling, colorblind mode support)
- Implement the UI following the UX spec and visual design spec
- **Use patterns from `design/ux/interaction-patterns.md`** — do not reinvent patterns that are already specified. If a pattern almost fits but needs modification, note the deviation and flag it for ux-designer review.
- **UI NEVER owns or modifies game state** — display only; emit events for all player actions
- All text through the localization system — no hardcoded player-facing strings
- Support both input methods (keyboard/mouse AND gamepad)
- Implement accessibility features per the committed tier in `design/accessibility-requirements.md`
- Wire up data binding to game state
- **If any new interaction pattern is created during implementation** (i.e., something not already in the pattern library), add it to `design/ux/interaction-patterns.md` before marking implementation complete
- Output: implemented UI feature
### Phase 4: Review (parallel)
Delegate in parallel:
- **ux-designer**: Verify implementation matches wireframes and interaction spec. Test keyboard-only and gamepad-only navigation. Check accessibility.
- **ux-designer**: Verify implementation matches wireframes and interaction spec. Test keyboard-only and gamepad-only navigation. Check accessibility features function correctly.
- **art-director**: Verify visual consistency with art bible. Check at minimum and maximum supported resolutions.
- **accessibility-specialist**: Verify compliance against the committed accessibility tier documented in `design/accessibility-requirements.md`. Flag any violations as blockers.
All three review streams must report before proceeding to Phase 5.
### Phase 5: Polish
- Address review feedback
- Verify animations are skippable and respect motion preferences
- Confirm UI sounds trigger through audio event system
- Address all review feedback
- Verify animations are skippable and respect the player's motion reduction preferences
- Confirm UI sounds trigger through the audio event system (no direct audio calls)
- Test at all supported resolutions and aspect ratios
- **Verify `design/ux/interaction-patterns.md` is up to date** — if any new patterns were introduced during this feature's implementation, confirm they have been added to the library
- **Confirm all HUD elements respect the visual budget** defined in `design/ux/hud.md` (element count, screen region allocations, maximum opacity values)
## Quick Reference — When to Use Which Skill
- `/ux-design` — Author a new UX spec for a screen, flow, or HUD from scratch
- `/ux-review` — Validate a completed UX spec before implementation
- `/team-ui [feature]` — Full pipeline from concept through polish (calls `/ux-design` and `/ux-review` internally)
- `/quick-design` — Small UI changes that don't need a full new UX spec
## Output
A summary report covering: UX spec status, visual design status, implementation status, accessibility compliance, input method support, and any outstanding issues.
A summary report covering: UX spec status, UX review verdict, visual design status, implementation status, accessibility compliance, input method support, interaction pattern library update status, and any outstanding issues.

756
.claude/skills/ux-design/SKILL.md Normal file
View file

@ -0,0 +1,756 @@
---
name: ux-design
description: "Guided, section-by-section UX spec authoring for a screen, flow, or HUD. Reads game concept, player journey, and relevant GDDs to provide context-aware design guidance. Produces ux-spec.md (per screen/flow) or hud-design.md using the studio templates."
argument-hint: "[screen/flow name] or 'hud' or 'patterns'"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, AskUserQuestion
context: fork
agent: ux-designer
---
When this skill is invoked:
## 1. Parse Arguments & Determine Mode
Three authoring modes exist based on the argument:
| Argument | Mode | Output file |
|----------|------|-------------|
| `hud` | HUD design | `design/ux/hud.md` |
| `patterns` | Interaction pattern library | `design/ux/interaction-patterns.md` |
| Any other value (e.g., `main-menu`, `inventory`) | UX spec for a screen or flow | `design/ux/[argument].md` |
| No argument | Ask the user | (see below) |
**If no argument is provided**, do not fail — ask instead. Use `AskUserQuestion`:
- "What are we designing today?"
- Options: "A specific screen or flow (I'll name it)", "The game HUD", "The interaction pattern library", "I'm not sure — help me figure it out"
If the user selects "I'll name it" or types a screen name, normalize it to kebab-case
for the filename (e.g., "Main Menu" becomes `main-menu`).
---
## 2. Gather Context (Read Phase)
Read all relevant context **before** asking the user anything. The skill's value
comes from arriving informed.
### 2a: Required Reads
- **Game concept**: Read `design/gdd/game-concept.md` — if missing, warn:
> "No game concept found. Run `/brainstorm` first to establish the game's
> foundation before designing UX."
> Continue anyway if the user asks.
### 2b: Player Journey
Read `design/player-journey.md` if it exists. For each relevant section, extract:
- Which journey phase(s) does this screen appear in?
- What is the player's emotional state on arrival at this screen?
- What player need is this screen serving in the journey?
- What critical moments (from the journey map) does this screen deliver?
If the player journey file does not exist, note the gap and proceed:
> "No player journey map found at `design/player-journey.md`. Designing without it
> means we'll be making assumptions about player context. Consider running a player
> journey session after this spec is drafted."
### 2c: GDD UI Requirements
Glob `design/gdd/*.md` and grep for `UI Requirements` sections. Read any GDD whose
UI Requirements section references this screen by name or category.
These GDD UI Requirements are the **requirements input** to this spec. Collect them
as a list of constraints the spec must satisfy.
If designing the HUD, read ALL GDD UI Requirements sections — the HUD aggregates
requirements from every system.
### 2d: Existing UX Specs
Glob `design/ux/*.md` and note which screens already have specs. For screens that
will link to or from the current screen, read their navigation/flow sections to
find the entry and exit points this spec must match.
### 2e: Interaction Pattern Library
If `design/ux/interaction-patterns.md` exists, read the pattern catalog index
(the list of pattern names and their one-line descriptions). Do not read full
pattern details — just the catalog. This tells you which patterns already exist
so you can reference them rather than reinvent them.
### 2f: Art Bible
Check for `docs/art-bible.md` or `design/art-bible.md`. If found, read the
visual direction section. UX layout must align with the aesthetic commitments
already made.
### 2g: Accessibility Requirements
Check for `design/accessibility-requirements.md`. If found, read it. The spec
must satisfy the accessibility tier committed to there.
### 2h: Present Context Summary
Before any design work, present a brief summary to the user:
> **Designing: [Screen/Flow Name]**
> - Mode: [UX Spec / HUD Design / Pattern Library]
> - Journey phase(s): [from player-journey.md, or "unknown — no journey map"]
> - GDD requirements feeding this spec: [count and names, or "none found"]
> - Related screens already specced: [list, or "none yet"]
> - Known patterns available: [count, or "no pattern library yet"]
> - Accessibility tier: [from requirements doc, or "not yet defined"]
Then ask: "Anything else I should read before we start, or shall we proceed?"
---
## 3. Create File Skeleton
Once the user confirms, **immediately** create the output file with empty section
headers. This ensures incremental writes have a target and work survives interruptions.
Ask: "May I create the skeleton file at `design/ux/[filename].md`?"
---
### Skeleton for UX Spec (screen or flow)
```markdown
# UX Spec: [Screen/Flow Name]
> **Status**: In Design
> **Author**: [user + ux-designer]
> **Last Updated**: [today's date]
> **Journey Phase(s)**: [from context]
> **Template**: UX Spec
---
## Purpose & Player Need
[To be designed]
---
## Player Context on Arrival
[To be designed]
---
## Layout Specification
### Information Hierarchy
[To be designed]
### Layout Zones
[To be designed]
### Component Inventory
[To be designed]
### ASCII Wireframe
[To be designed]
---
## States & Variants
[To be designed]
---
## Interaction Map
[To be designed]
---
## Data Requirements
[To be designed]
---
## Accessibility
[To be designed]
---
## Open Questions
[To be designed]
```
---
### Skeleton for HUD Design
```markdown
# HUD Design
> **Status**: In Design
> **Author**: [user + ux-designer]
> **Last Updated**: [today's date]
> **Template**: HUD Design
---
## HUD Philosophy
[To be designed]
---
## Information Architecture
### Full Information Inventory
[To be designed]
### Categorization
[To be designed]
---
## Layout Zones
[To be designed]
---
## HUD Elements
[To be designed]
---
## Dynamic Behaviors
[To be designed]
---
## Platform & Input Variants
[To be designed]
---
## Accessibility
[To be designed]
---
## Open Questions
[To be designed]
```
---
### Skeleton for Interaction Pattern Library
```markdown
# Interaction Pattern Library
> **Status**: In Design
> **Author**: [user + ux-designer]
> **Last Updated**: [today's date]
> **Template**: Interaction Pattern Library
---
## Overview
[To be designed]
---
## Pattern Catalog
[To be designed]
---
## Patterns
[Individual pattern entries added here as they are defined]
---
## Gaps & Patterns Needed
[To be designed]
---
## Open Questions
[To be designed]
```
---
After writing the skeleton, update `production/session-state/active.md` with:
- Task: Designing [screen/flow name] UX spec
- Current section: Starting (skeleton created)
- File: design/ux/[filename].md
---
## 4. Section-by-Section Authoring
Walk through each section in order. For **each section**, follow this cycle:
```
Context -> Questions -> Options -> Decision -> Draft -> Approval -> Write
```
1. **Context**: State what this section needs to contain and surface any relevant
constraints from context gathered in Phase 2.
2. **Questions**: Ask what is needed to draft this section. Use `AskUserQuestion`
for constrained choices, conversational text for open-ended exploration.
3. **Options**: Where design choices exist, present 2-4 approaches with pros/cons.
Explain reasoning in conversation, then use `AskUserQuestion` to capture the decision.
4. **Decision**: User picks an approach or provides custom direction.
5. **Draft**: Write the section content in conversation for review. Flag provisional
assumptions explicitly.
6. **Approval**: "Does this capture it? Any changes before I write it to the file?"
7. **Write**: Use `Edit` to replace the `[To be designed]` placeholder with approved
content. Confirm the write.
After writing each section, update `production/session-state/active.md`.
---
### Section Guidance: UX Spec Mode
#### Section A: Purpose & Player Need
This section is the foundation. Every other decision flows from it.
**Questions to ask**:
- "What player goal does this screen serve? What is the player trying to DO here?"
- "What would go wrong if this screen didn't exist or was hard to use?"
- "Complete this sentence: 'The player arrives at this screen wanting to ___.' "
Cross-reference the player journey context gathered in Phase 2. The stated purpose
must align with the journey phase and emotional state.
---
#### Section B: Player Context on Arrival
**Questions to ask**:
- "When in the game does a player first encounter this screen?"
- "What were they just doing immediately before reaching this screen?"
- "What emotional state should the design assume? (calm, stressed, curious, time-pressured)"
- "Do players arrive at this screen voluntarily, or are they sent here by the game?"
Offer to map this against the journey phases if the player journey doc exists.
---
#### Section C: Layout Specification
This is the largest and most interactive section. Work through it in sub-sections:
**Sub-section 1 — Information Hierarchy** (establish this before any layout):
- Ask the user to list every piece of information this screen must communicate.
- Then ask them to rank the items: "What is the single most important thing a player
needs to see first? What is second? What can be discovered rather than immediately visible?"
- Present the resulting hierarchy for approval before moving to zones.
**Sub-section 2 — Layout Zones**:
- Based on the information hierarchy, propose rough screen zones (header, content
area, action bar, sidebar, etc.).
- Offer 2-3 zone arrangements with rationale for each. Reference platform and
input context gathered from game concept.
- Ask: "Do any of these match your mental image, or shall we build a custom arrangement?"
**Sub-section 3 — Component Inventory**:
- For each zone, list the UI components it contains. For each component, note:
- Component type (button, list, card, stat display, input field, etc.)
- Content it displays
- Whether it is interactive
- If it uses an existing pattern from the library (reference by pattern name)
- If it introduces a new pattern (flag for later addition to the library)
**Sub-section 4 — ASCII Wireframe**:
- Offer to generate an ASCII wireframe based on the zone layout and component list.
- Use `AskUserQuestion`: "Want an ASCII wireframe as part of this spec?"
- Options: "Yes, include one", "No, I'll attach a separate file"
- If yes, produce the wireframe in conversation first. Ask for feedback before
writing it to file.
---
#### Section D: States & Variants
Guide the user to think beyond the happy path.
**Questions to ask** (work through these one at a time):
- "What does this screen look like the very first time a player sees it, when there
is no data yet? (empty state)"
- "What happens when something goes wrong — an error, a failed action, a missing
resource? (error state)"
- "Is there ever a loading wait on this screen? If so, what does it show? (loading state)"
- "Are there any player progression states that change what this screen shows? For
example, locked content, premium content, or tutorial-mode overlays?"
- "Does this screen behave differently on any supported platform? (platform variant)"
Present the collected states as a table for approval:
| State / Variant | Trigger | What Changes |
|-----------------|---------|--------------|
| Default | Normal load | — |
| Empty | No data available | [content area description] |
| [etc.] | [trigger] | [changes] |
---
#### Section E: Interaction Map
For each interactive component identified in the Layout Specification, define:
- The action (tap, click, press, hold, scroll, drag)
- The platform input(s) that trigger it (mouse click, gamepad A, keyboard Enter)
- The immediate feedback (visual, audio, haptic)
- The outcome (navigation target, state change, data write)
Ask up front: "Which input methods does this game target? I'll tailor the
interaction map to those." Reference game concept for platform targets.
Work through components one at a time rather than asking for all at once.
For navigation actions (going to another screen), verify the target matches
an existing UX spec or note it as a spec dependency.
---
#### Section F: Data Requirements
Cross-reference the GDD UI Requirements sections gathered in Phase 2.
For each piece of information the screen displays, ask:
- "Where does this data come from? Which system owns it?"
- "Does this screen need to write data back, or is it read-only?"
- "Is any of this data time-sensitive or real-time? (health bars, cooldown timers)"
Flag any case where the UI would need to own or manage game state as an architectural
concern. UX specs define what the UI needs; they do not dictate how the data is
delivered. That is an architecture decision.
Present the data requirements as a table:
| Data | Source System | Read / Write | Notes |
|------|--------------|--------------|-------|
| [item] | [system] | Read | — |
| [item] | [system] | Write | [concern if any] |
---
#### Section G: Accessibility
Cross-reference `design/accessibility-requirements.md` if it exists.
Walk through the ux-designer agent's standard checklist for this screen:
- Keyboard-only navigation path through all interactive elements
- Gamepad navigation order (if applicable)
- Text contrast and minimum readable font sizes
- Color-independent communication (no information conveyed by color alone)
- Screen reader considerations for any non-text elements
- Any motion or animation that needs a reduced-motion alternative
Use `AskUserQuestion` to surface any open questions on accessibility tier:
- "Has the accessibility tier been committed to for this project?"
- Options: "Yes, read from requirements doc", "Not yet — let's flag it as a question", "Skip accessibility section for now"
---
### Section Guidance: HUD Design Mode
HUD design follows a different order from UX spec mode. Begin with philosophy;
do not touch layout until the information architecture is complete.
#### Section A: HUD Philosophy
Ask the user to describe the game's relationship with on-screen information in
1-2 sentences.
Offer framing examples to help:
- "Nearly HUD-free — atmosphere requires unobstructed immersion (e.g., Hollow Knight, Firewatch)"
- "Minimal but present — only critical information visible, everything else contextual (e.g., Dark Souls)"
- "Information-dense — all decision-relevant data always visible (e.g., Diablo IV, StarCraft II)"
- "Adaptive — HUD density responds to combat state, exploration mode, menus (e.g., God of War)"
This philosophy becomes the design constraint for every subsequent HUD decision.
If a proposed element conflicts with the stated philosophy, surface that conflict.
---
#### Section B: Information Architecture
Complete this before any layout work. Do not skip it.
**Step 1 — Full information inventory**:
Pull all information from GDD UI Requirements sections gathered in Phase 2.
Present the full list: "These are all the things your game systems say they need
to communicate to the player on screen."
**Step 2 — Categorization**:
For each item, ask the user to categorize it:
| Category | Description |
|----------|-------------|
| **Must Show** | Always visible, player needs it for core decisions |
| **Contextual** | Visible only when relevant (in combat, near interactable, etc.) |
| **On Demand** | Player must actively request it (toggle, hold button) |
| **Hidden** | Communicated through world/audio, never on-screen text |
Use `AskUserQuestion` to step through items in groups of 3-4, not all at once.
This is the most consequential design decision in the HUD — do not rush it.
**Conflict check**: If the information philosophy (Section A) says "nearly HUD-free"
but the Must Show list is growing long, surface the conflict explicitly:
> "The current Must Show list has [N] items. That may conflict with the HUD-free
> philosophy. Options: reduce the Must Show list, revise the philosophy, or define
> a hybrid approach where HUD is absent in exploration and present in combat."
---
#### Section C: Layout Zones
Only after the information architecture is approved, design layout zones.
Base layout on:
- Which items are Must Show (they drive the permanent zone decisions)
- Where player attention naturally goes during gameplay (center-screen for action games,
corners for strategy games)
- Platform and aspect ratio targets
Offer 2-3 zone arrangements. Include rationale based on the HUD philosophy and the
categorization from Section B.
---
#### Section D: HUD Elements
For each element in the layout, specify:
- Element name and category (Must Show / Contextual / On Demand)
- Content displayed
- Visual form (bar, number, icon, counter, map)
- Update behavior (real-time, event-driven, player-queried)
- Contextual trigger (if not always visible)
- Animation behavior (does it pulse when low? Fade in? Slam in?)
Work element by element. Reference the interaction pattern library if relevant patterns
exist for status displays, resource bars, or cooldown indicators.
---
#### Sections E, F, G: Dynamic Behaviors, Platform Variants, Accessibility
These follow the same structure as the UX spec equivalents. See UX Spec section
guidance for D (States/Variants), E (Interactions), and G (Accessibility).
For the HUD specifically, emphasize:
- Dynamic Behaviors: what causes the HUD to change density mid-gameplay?
- Platform Variants: does mobile/console require different element sizes or positions?
---
### Section Guidance: Interaction Pattern Library Mode
Pattern library authoring is additive and catalog-driven, not linear.
#### Phase 1: Catalog Existing Patterns
Glob `design/ux/*.md` (excluding `interaction-patterns.md`) and read the Component
Inventory and Interaction Map sections of each spec. Extract every interaction
pattern used.
Present the extracted list: "Based on existing UX specs, these patterns are already
in use in the game:"
- [Pattern name]: used in [screen], [screen]
- [etc.]
Ask: "Are there patterns you know exist but aren't in existing specs yet? List any
additional ones now."
---
#### Phase 2: Formalize Each Pattern
For each pattern (existing or new), document:
```markdown
### [Pattern Name]
**Category**: Navigation / Input / Feedback / Data Display / Modal / Overlay / [other]
**Used In**: [list of screens]
**Description**: [One paragraph explaining what this pattern is and when to use it]
**Specification**:
- [Component behavior]
- [Input mapping]
- [Visual/audio feedback]
- [Accessibility requirements for this pattern]
**When to Use**: [Conditions where this pattern is appropriate]
**When NOT to Use**: [Conditions where another pattern is more appropriate]
**Reference**: [Screenshot path or ASCII example, if available]
```
Work through patterns in groups. Offer: "Shall I draft the first batch based on what
I've found in the existing specs, or do you want to define them one by one?"
---
#### Phase 3: Identify Gaps
After cataloging known patterns, ask:
- "Are there screens or interactions planned that would need patterns not yet
in this library?"
- "Are there any patterns in existing specs that feel inconsistent with each
other and should be consolidated?"
Document gaps in the Gaps section for follow-up.
---
## 5. Cross-Reference Check
Before marking the spec as ready for review, run these checks:
**1. GDD requirement coverage**: Does every GDD UI Requirement that references
this screen have a corresponding element in this spec? Present any gaps.
**2. Pattern library alignment**: Are all interaction patterns used in this spec
referenced by name? If a new pattern was invented during this spec session, flag
it for addition to the pattern library:
> "This spec uses [pattern name], which isn't in the pattern library yet.
> Want to add it now, or flag it as a gap?"
**3. Navigation consistency**: Do the entry/exit points in this spec match the
navigation map in any related specs? Flag mismatches.
**4. Accessibility coverage**: Does the spec address the accessibility tier
committed to in `design/accessibility-requirements.md`? If not, flag open questions.
**5. Empty states**: Does every data-dependent element have an empty state defined?
Flag any that don't.
Present the check results:
> **Cross-Reference Check: [Screen Name]**
> - GDD requirements: [N of M covered / all covered]
> - New patterns to add to library: [list or "none"]
> - Navigation mismatches: [list or "none"]
> - Accessibility gaps: [list or "none"]
> - Missing empty states: [list or "none"]
---
## 6. Handoff
When all sections are approved and written:
### 6a: Update Session State
Update `production/session-state/active.md` with:
- Task: [screen-name] UX spec
- Status: Complete (or In Review)
- File: design/ux/[filename].md
- Sections: All written
- Next: [suggestion]
### 6b: Suggest Next Step
Use `AskUserQuestion`:
- "The spec is complete. What's next?"
- Options:
- "Run `/ux-review` to validate this spec"
- "Design another screen"
- "Update the interaction pattern library with new patterns from this spec"
- "Stop here for this session"
### 6c: Cross-Link Related Specs
If other UX specs link to or from this screen, note which ones should reference
this spec. Do not edit those files without asking — just name them.
---
## 7. Recovery & Resume
If the session is interrupted (compaction, crash, new session):
1. Read `production/session-state/active.md` — it records the current screen
and which sections are complete.
2. Read `design/ux/[filename].md` — sections with real content are done;
sections with `[To be designed]` still need work.
3. Resume from the next incomplete section — no need to re-discuss completed ones.
This is why incremental writing matters: every approved section survives any
disruption.
---
## 8. Specialist Agent Routing
This skill uses `ux-designer` as the primary agent (set in frontmatter). For
specific sub-topics, additional context or coordination may be needed:
| Topic | Coordinate with |
|-------|----------------|
| Visual aesthetics, color, layout feel | `art-director` — UX spec defines zones; art defines how they look |
| Implementation feasibility (engine constraints) | `ui-programmer` — before finalizing component inventory |
| Gameplay data requirements | `game-designer` — when data ownership is unclear |
| Narrative/lore visible in the UI | `narrative-director` — for flavor text, item names, lore panels |
| Accessibility tier decisions | `ux-designer` (owns this) |
When delegating to another agent via the Task tool:
- Provide: screen name, game concept summary, the specific question needing expert input
- The agent returns analysis to this session
- This session presents the agent's output to the user
- The user decides; this session writes to file
- Agents do NOT write to files directly — this session owns all file writes
---
## Collaborative Protocol
This skill follows the collaborative design principle at every step:
1. **Question -> Options -> Decision -> Draft -> Approval** for every section
2. **AskUserQuestion** at every decision point (Explain -> Capture pattern):
- Phase 2: "Ready to start, or need more context?"
- Phase 3: "May I create the skeleton?"
- Phase 4 (each section): design questions, approach options, draft approval
- Phase 5: "Run cross-reference check? What's next?"
3. **"May I write to [filepath]?"** before the skeleton and before each section write
4. **Incremental writing**: Each section is written to file immediately after approval
5. **Session state updates**: After every section write
**Aesthetic deference**: When layout or visual choices come down to personal taste,
present the options and ask. Do not select a layout because it is "standard" — always
confirm. The user is the creative director.
**Conflict surfacing**: When a GDD requirement and the available screen real estate
conflict, surface the conflict and present resolution options. Never silently drop
a requirement. Never silently expand the layout without flagging it.
**Never** auto-generate the full spec and present it as a fait accompli.
**Never** write a section without user approval.
**Never** contradict an existing approved UX spec without flagging the conflict.
**Always** show where decisions come from (GDD requirements, player journey, user choices).

259
.claude/skills/ux-review/SKILL.md Normal file
View file

@ -0,0 +1,259 @@
---
name: ux-review
description: "Validates a UX spec, HUD design, or interaction pattern library for completeness, accessibility compliance, GDD alignment, and implementation readiness. Produces APPROVED / NEEDS REVISION / MAJOR REVISION NEEDED verdict with specific gaps."
argument-hint: "[file-path or 'all' or 'hud' or 'patterns']"
user-invocable: true
allowed-tools: Read, Glob, Grep
context: fork
agent: ux-designer
---
## Overview
Validates UX design documents before they enter the implementation pipeline.
Acts as the quality gate between UX Design and Visual Design/Implementation in
the `/team-ui` pipeline.
**Run this skill:**
- After completing a UX spec with `/ux-design`
- Before handing off to `ui-programmer` or `art-director`
- Before the Pre-Production to Production gate check (which requires key screens
to have reviewed UX specs)
- After major revisions to a UX spec
**Verdict levels:**
- **APPROVED** — spec is complete, consistent, and implementation-ready
- **NEEDS REVISION** — specific gaps found; fix before handoff but not a full redesign
- **MAJOR REVISION NEEDED** — fundamental issues with scope, player need, or
completeness; needs significant rework
---
## Phase 1: Parse Arguments
- **Specific file path** (e.g., `/ux-review design/ux/inventory.md`): validate
that one document
- **`all`**: find all files in `design/ux/` and validate each
- **`hud`**: validate `design/ux/hud.md` specifically
- **`patterns`**: validate `design/ux/interaction-patterns.md` specifically
- **No argument**: ask the user which spec to validate
For `all`, output a summary table first (file | verdict | primary issue) then
full detail for each.
---
## Phase 2: Load Cross-Reference Context
Before validating any spec, load:
1. The accessibility tier committed to in `design/accessibility-requirements.md`
(if it exists)
2. The interaction pattern library at `design/ux/interaction-patterns.md` (if
it exists)
3. The GDDs referenced in the spec's header (read their UI Requirements sections)
4. The player journey map at `design/player-journey.md` (if it exists) for
context-arrival validation
---
## Phase 3A: UX Spec Validation Checklist
Run all checks against a `ux-spec.md`-based document.
### Completeness (required sections)
- [ ] Document header present with Status, Author, Platform Target
- [ ] Purpose & Player Need — has a player-perspective need statement (not
developer-perspective)
- [ ] Player Context on Arrival — describes player's state and prior activity
- [ ] Navigation Position — shows where screen sits in hierarchy
- [ ] Entry & Exit Points — all entry sources and exit destinations documented
- [ ] Layout Specification — zones defined, component inventory table present
- [ ] States & Variants — at minimum: loading, empty/populated, and error states
documented
- [ ] Interaction Map — covers all target input methods (check platform target
in header)
- [ ] Data Requirements — every displayed data element has a source system and owner
- [ ] Events Fired — every player action has a corresponding event or null
explanation
- [ ] Transitions & Animations — at least enter/exit transitions specified
- [ ] Accessibility Requirements — screen-level requirements present
- [ ] Localization Considerations — max character counts for text elements
- [ ] Acceptance Criteria — at least 5 specific testable criteria
### Quality Checks
**Player Need Clarity**
- [ ] Purpose is written from player perspective, not system/developer perspective
- [ ] Player goal on arrival is unambiguous ("The player arrives wanting to ___")
- [ ] The player context on arrival is specific (not just "they opened the
inventory")
**Completeness of States**
- [ ] Error state is documented (not just happy path)
- [ ] Empty state is documented (no data scenario)
- [ ] Loading state is documented if the screen fetches async data
- [ ] Any state with a timer or auto-dismiss is documented with duration
**Input Method Coverage**
- [ ] If platform includes PC: keyboard-only navigation is fully specified
- [ ] If platform includes console/gamepad: d-pad navigation and face button
mapping documented
- [ ] No interaction requires mouse-like precision on gamepad
- [ ] Focus order is defined (Tab order for keyboard, d-pad order for gamepad)
**Data Architecture**
- [ ] No data element has "UI" listed as the owner (UI must not own game state)
- [ ] Update frequency is specified for all real-time data (not just "realtime" —
what triggers update?)
- [ ] Null handling is specified for all data elements (what shows when data is
unavailable?)
**Accessibility**
- [ ] Accessibility tier from `accessibility-requirements.md` is matched or exceeded
- [ ] If Basic tier: no color-only information indicators
- [ ] If Standard tier+: focus order documented, text contrast ratios specified
- [ ] If Comprehensive tier+: screen reader announcements for key state changes
- [ ] Colorblind check: any color-coded elements have non-color alternatives
**GDD Alignment**
- [ ] Every GDD UI Requirement referenced in the header is addressed in this spec
- [ ] No UI element displays or modifies game state without a corresponding GDD
requirement
- [ ] No GDD UI Requirement is missing from this spec (cross-check the referenced
GDD sections)
**Pattern Library Consistency**
- [ ] All interactive components reference the pattern library (or note they are
new patterns)
- [ ] No pattern behavior is re-specified from scratch if it already exists in
the pattern library
- [ ] Any new patterns invented in this spec are flagged for addition to the
pattern library
**Localization**
- [ ] Character limit warnings present for all text-heavy elements
- [ ] Any layout-critical text has been flagged for 40% expansion accommodation
**Acceptance Criteria Quality**
- [ ] Criteria are specific enough for a QA tester who hasn't seen the design docs
- [ ] Performance criterion present (screen opens within Xms)
- [ ] Resolution criterion present
- [ ] No criterion requires reading another document to evaluate
---
## Phase 3B: HUD Validation Checklist
Run all checks against a `hud-design.md`-based document.
### Completeness
- [ ] HUD Philosophy defined
- [ ] Information Architecture table covers ALL systems with UI Requirements in GDDs
- [ ] Layout Zones defined with safe zone margins for all target platforms
- [ ] Every HUD element has a full specification (zone, visibility trigger, data
source, priority)
- [ ] HUD States by Gameplay Context covers at minimum: exploration, combat,
dialogue/cutscene, paused
- [ ] Visual Budget defined (max simultaneous elements, max screen %)
- [ ] Platform Adaptation covers all target platforms
- [ ] Tuning Knobs present for player-adjustable elements
### Quality Checks
- [ ] No HUD element covers the center play area without a visibility rule to
hide it
- [ ] Every information item that exists in any GDD is either in the HUD or
explicitly categorized as "hidden/demand"
- [ ] All color-coded HUD elements have colorblind variants
- [ ] HUD elements in the Feedback & Notification section have queue/priority
behavior defined
- [ ] Visual Budget compliance: total simultaneous elements is within budget
### GDD Alignment
- [ ] All systems in `design/gdd/systems-index.md` with UI category have
representation in HUD (or justified absence)
---
## Phase 3C: Pattern Library Validation Checklist
- [ ] Pattern catalog index is current (matches actual patterns in document)
- [ ] All standard control patterns are specified: button variants, toggle,
slider, dropdown, list, grid, modal, dialog, toast, tooltip, progress bar,
input field, tab bar, scroll
- [ ] All game-specific patterns needed by current UX specs are present
- [ ] Each pattern has: When to Use, When NOT to Use, full state specification,
accessibility spec, implementation notes
- [ ] Animation Standards table present
- [ ] Sound Standards table present
- [ ] No conflicting behaviors between patterns (e.g., "Back" behavior consistent
across all navigation patterns)
---
## Phase 4: Output the Verdict
```markdown
## UX Review: [Document Name]
**Date**: [date]
**Reviewer**: ux-review skill
**Document**: [file path]
**Platform Target**: [from header]
**Accessibility Tier**: [from header or accessibility-requirements.md]
### Completeness: [X/Y sections present]
- [x] Purpose & Player Need
- [ ] States & Variants — MISSING: error state not documented
### Quality Issues: [N found]
1. **[Issue title]** [BLOCKING / ADVISORY]
- What's wrong: [specific description]
- Where: [section name]
- Fix: [specific action to take]
### GDD Alignment: [ALIGNED / GAPS FOUND]
- GDD [name] UI Requirements — [X/Y requirements covered]
- Missing: [list any uncovered GDD requirements]
### Accessibility: [COMPLIANT / GAPS / NON-COMPLIANT]
- Target tier: [tier]
- [list specific accessibility findings]
### Pattern Library: [CONSISTENT / INCONSISTENCIES FOUND]
- [findings]
### Verdict: APPROVED / NEEDS REVISION / MAJOR REVISION NEEDED
**Blocking issues**: [N] — must be resolved before implementation
**Advisory issues**: [N] — recommended but not blocking
[For APPROVED]: This spec is ready for handoff to `/team-ui` Phase 2
(Visual Design).
[For NEEDS REVISION]: Address the [N] blocking issues above, then re-run
`/ux-review`.
[For MAJOR REVISION NEEDED]: The spec has fundamental gaps in [areas].
Recommend returning to `/ux-design` to rework [sections].
```
---
## Phase 5: Collaborative Protocol
This skill is READ-ONLY — it never edits or writes files. It reports findings only.
After delivering the verdict:
- For **APPROVED**: suggest running `/team-ui` to begin implementation coordination
- For **NEEDS REVISION**: offer to help fix specific gaps ("Would you like me to
help draft the missing error state?") — but do not auto-fix; wait for user
instruction
- For **MAJOR REVISION NEEDED**: suggest returning to `/ux-design` with the
specific sections to rework
Never block the user from proceeding — the verdict is advisory. Document risks,
present findings, let the user decide whether to proceed despite concerns. A user
who chooses to proceed with a NEEDS REVISION spec takes on the documented risk.