design-system

When this skill is invoked: ## 1. Parse Arguments & Validate Resolve the review mode (once, store for all gate spawns this run): 1. If `--review [full|lean|solo]` was passed → use that 2. Else read `production/review-mode.txt` → use that value 3. Else → default to `lean` See `docs/studio/director-gates.md` for the full check pattern. A system name or retrofit path is **required**. If missing: 1. Check if `design/gdd/systems-index.md` exists. 2. If it exists: read it, find the highest-priority system with status "Not Started" or equivalent, and ask the user directly in plain text: - Prompt: "The next system in your design order is **[system-name]** ([priority] | [layer]). Start designing it?" - Options: `[A] Yes — design [system-name]` / `[B] Pick a different system` / `[C] Stop here` - If [A]: proceed with that system name. If [B]: ask which system to design (plain text). If [C]: exit. 3. If no systems index exists, fail with: > "Usage: `$design-system <system-name>` — e.g., `$design-system movement` > Or to fill gaps in an existing GDD: `$design-system retrofit design/gdd/[system-name].md` > No systems index found. Run `$map-systems` first to map your systems and get the design order." **Detect retrofit mode:** If the argument starts with `retrofit` or the argument is a file path to an existing `.md` file in `design/gdd/`, enter **retrofit mode**: 1. Read the existing GDD file. 2. Identify which of the 8 required sections are present (scan for section headings). Required sections: Overview, Player Fantasy, Detailed Design/Rules, Formulas, Edge Cases, Dependencies, Tuning Knobs, Acceptance Criteria. 3. Identify which sections contain only placeholder text (`[To be designed]` or equivalent — blank, a single line, or obviously incomplete). 4. Present to the user before doing anything: ``` ## Retrofit: [System Name] File: design/gdd/[filename].md Sections already written (will not be touched): ✓ [section name] ✓ [section name] Missing or incomplete sections (will be authored): ✗ [section name] — missing ✗ [section name] — placeholder only ``` 5. Ask: "Shall I fill the [N] missing sections? I will not modify any existing content." 6. If yes: proceed to **Phase 2 (Gather Context)** as normal, but in **Phase 3** skip creating the skeleton (file already exists) and in **Phase 4** skip sections that are already complete. Only run the section cycle for missing/ incomplete sections. 7. **Never overwrite existing section content.** Use Edit tool to replace only `[To be designed]` placeholders or empty section bodies. If NOT in retrofit mode, normalize the system name to kebab-case for the filename (e.g., "combat system" becomes `combat-system`). --- ## 2. Gather Context (Read Phase) Read all relevant context **before** asking the user anything. This is the skill's primary advantage over ad-hoc design — it arrives informed. ### 2a: Required Reads - **Game concept**: Read `design/gdd/game-concept.md` — fail if missing: > "No game concept found. Run `$brainstorm` first." - **Systems index**: Read `design/gdd/systems-index.md` — fail if missing: > "No systems index found. Run `$map-systems` first to map your systems." - **Target system**: Find the system in the index. If not listed, warn: > "[system-name] is not in the systems index. Would you like to add it, or > design it as an off-index system?" - **Entity registry**: Read `design/registry/entities.yaml` if it exists. Extract all entries referenced by or relevant to this system (grep `referenced_by.*[system-name]` and `source.*[system-name]`). Hold these in context as **known facts** — values that other GDDs have already established and this GDD must not contradict. - **Reflexion log**: Read `docs/consistency-failures.md` if it exists. Extract entries whose Domain matches this system's category. These are recurring conflict patterns — present them under "Past failure patterns" in the Phase 2d context summary so the user knows where mistakes have occurred before in this domain. ### 2b: Dependency Reads From the systems index, identify: - **Upstream dependencies**: Systems this one depends on. Read their GDDs if they exist (these contain decisions this system must respect). - **Downstream dependents**: Systems that depend on this one. Read their GDDs if they exist (these contain expectations this system must satisfy). For each dependency GDD that exists, extract and hold in context: - Key interfaces (what data flows between the systems) - Formulas that reference this system's outputs - Edge cases that assume this system's behavior - Tuning knobs that feed into this system ### 2c: Optional Reads - **Game pillars**: Read `design/gdd/game-pillars.md` if it exists - **Existing GDD**: Read `design/gdd/[system-name].md` if it exists (resume, don't restart from scratch) - **Related GDDs**: Glob `design/gdd/*.md` and read any that are thematically related (e.g., if designing a system that overlaps with another in scope, read the related GDD even if it's not a formal dependency) ### 2d: Present Context Summary Before starting design work, present a brief summary to the user: > **Designing: [System Name]** > - Priority: [from index] | Layer: [from index] > - Depends on: [list, noting which have GDDs vs. undesigned] > - Depended on by: [list, noting which have GDDs vs. undesigned] > - Existing decisions to respect: [key constraints from dependency GDDs] > - Pillar alignment: [which pillar(s) this system primarily serves] > - **Known cross-system facts (from registry):** > - [entity_name]: [attribute]=[value], [attribute]=[value] (owned by [source GDD]) > - [item_name]: [attribute]=[value], [attribute]=[value] (owned by [source GDD]) > - [formula_name]: variables=[list], output=[min–max] (owned by [source GDD]) > - [constant_name]: [value] [unit] (owned by [source GDD]) > *(These values are locked — if this GDD needs different values, surface > the conflict before writing. Do not silently use different numbers.)* > > If no registry entries are relevant: omit the "Known cross-system facts" section. If any upstream dependencies are undesigned, warn: > "[dependency] doesn't have a GDD yet. We'll need to make assumptions about > 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 `docs/studio/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:** Ask the user directly in plain text: - "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" --- Ask the user directly in plain text: - "Ready to start designing [system-name]?" - Options: "Yes, let's go", "Show me more context first", "Design a dependency first" --- ## 3. Create File Skeleton Once the user confirms, **immediately** create the GDD file with empty section headers. This ensures incremental writes have a target. Use the template structure from `docs/studio/templates/game-design-document.md`: ```markdown # [System Name] > **Status**: In Design > **Author**: [user + agents] > **Last Updated**: [today's date] > **Implements Pillar**: [from context] ## Overview [To be designed] ## Player Fantasy [To be designed] ## Detailed Design ### Core Rules [To be designed] ### States and Transitions [To be designed] ### Interactions with Other Systems [To be designed] ## Formulas [To be designed] ## Edge Cases [To be designed] ## Dependencies [To be designed] ## Tuning Knobs [To be designed] ## Visual/Audio Requirements [To be designed] ## UI Requirements [To be designed] ## Acceptance Criteria [To be designed] ## Open Questions [To be designed] ``` Ask: "May I create the skeleton file at `design/gdd/[system-name].md`?" After writing, update `production/session-state/active.md`: - Use Glob to check if the file exists. - If it **does not exist**: use the **Write** tool to create it. Never attempt Edit on a file that may not exist. - If it **already exists**: use the **Edit** tool to update the relevant fields. File content: - Task: Designing [system-name] GDD - Current section: Starting (skeleton created) - File: design/gdd/[system-name].md --- ## 4. Section-by-Section Design Walk through each section in order. For **each section**, follow this cycle: ### The Section Cycle ``` Context -> Questions -> Options -> Decision -> Draft -> Approval -> Write ``` 1. **Context**: State what this section needs to contain, and surface any relevant decisions from dependency GDDs that constrain it. 2. **Questions**: Ask clarifying questions specific to this section. Use a concise plain-text choice list for constrained questions, conversational text for open-ended exploration. 3. **Options**: Where the section involves design choices (not just documentation), present 2-4 approaches with pros/cons. Explain reasoning in conversation text, then ask the user directly in plain text to capture the decision. 4. **Decision**: User picks an approach or provides custom direction. 5. **Draft**: Write the section content in conversation text for review. Flag any provisional assumptions about undesigned dependencies. 6. **Approval**: Immediately after the draft — in the SAME response — use a concise plain-text choice list. **NEVER use plain text. NEVER skip this step.** - Prompt: "Approve the [Section Name] section?" - Options: `[A] Approve — write it to file` / `[B] Make changes — describe what to fix` / `[C] Start over` **The draft and the approval widget MUST appear together in one response. If the draft appears without the widget, the user is left at a blank prompt with no path forward — this is a protocol violation.** 7. **Write**: Use the Edit tool to replace the placeholder with the approved content. **CRITICAL**: Always include the section heading in the `old_string` to ensure uniqueness — never match `[To be designed]` alone, as multiple sections use the same placeholder and the Edit tool requires a unique match. Use this pattern: ``` old_string: "## [Section Name]\n\n[To be designed]" new_string: "## [Section Name]\n\n[approved content]" ``` Confirm the write. 8. **Registry conflict check** (Sections C and D only — Detailed Design and Formulas): After writing, scan the section content for entity names, item names, formula names, and numeric constants that appear in the registry. For each match: - Compare the value just written against the registry entry. - If they differ: **surface the conflict immediately** before starting the next section. Do not continue silently. > "Registry conflict: [name] is registered in [source GDD] as [registry_value]. > This section just wrote [new_value]. Which is correct?" - If new (not in registry): flag it as a candidate for registry registration (will be handled in Phase 5). After writing each section, update `production/session-state/active.md` with the completed section name. Use Glob to check if the file exists — use Write to create it if absent, Edit to update it if present. ### Section-Specific Guidance Each section has unique design considerations and may benefit from specialist agents: --- ### Section A: Overview **Goal**: One paragraph a stranger could read and understand. **Derive recommended options before building the widget**: Read the system's category and layer from the systems index (already in context from Phase 2), then determine the recommended option for each tab: - **Framing tab**: Foundation/Infrastructure layer → `[A]` recommended. Player-facing categories (Combat, UI, Dialogue, Character, Animation, Visual Effects, Audio) → `[C] Both` recommended. - **ADR ref tab**: Glob `docs/architecture/adr-*.md` and grep for the system name in the GDD Requirements section of any ADR. If a matching ADR is found → `[A] Yes — cite the ADR` recommended. If none found → `[B] No` recommended. - **Fantasy tab**: Foundation/Infrastructure layer → `[B] No` recommended. All other categories → `[A] Yes` recommended. Append `(Recommended)` to the appropriate option text in each tab. **Framing questions (ask BEFORE drafting)**: Ask the user directly in plain text with a multi-tab widget: - Tab "Framing" — "How should the overview frame this system?" Options: `[A] As a data/infrastructure layer (technical framing)` / `[B] Through its player-facing effect (design framing)` / `[C] Both — describe the data layer and its player impact` - Tab "ADR ref" — "Should the overview reference the existing ADR for this system?" Options: `[A] Yes — cite the ADR for implementation details` / `[B] No — keep the GDD at pure design level` - Tab "Fantasy" — "Does this system have a player fantasy worth stating?" Options: `[A] Yes — players feel it directly` / `[B] No — pure infrastructure, players feel what it enables` Use the user's answers to shape the draft. Do NOT answer these questions yourself and auto-draft. **Questions to ask**: - What is this system in one sentence? - How does a player interact with it? (active/passive/automatic) - Why does this system exist — what would the game lose without it? **Cross-reference**: Check that the description aligns with how the systems index describes it. Flag discrepancies. **Design vs. implementation boundary**: Overview questions must stay at the behavior level — what the system *does*, not *how it is built*. If implementation questions arise during the Overview (e.g., "Should this use an Autoload singleton or a signal bus?"), note them as "→ becomes an ADR" and move on. Implementation patterns belong