Guided, section-by-section GDD authoring for a single game system. Gathers context from existing docs, walks through each required section collaboratively, cross-references dependencies, and writes incrementally to file.

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 .claude/docs/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 use AskUserQuestion : 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: 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 .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: 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" 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 .claude/docs/templates/game design document.md : Ask: "May I create the skeleton file at design/gdd/[system name].md ?" If the user declines: Stop with the following message: "Verdict: BLOCKED — skeleton creation declined. The design session cannot proceed without the skeleton file, as all subsequent phases use it as the base. Re run /design system [system] when ready to create the file." Do not proceed to Section A. 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 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 AskUserQuestion 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 use AskUserQuestion 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 AskUserQuestion . 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: 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 bef

design-system