/design-system

name: design-system
description: "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."
argument-hint: "<system-name> [--review full|lean|solo]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Task, AskUserQuestion, TodoWrite
model: sonnet

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:

   ## 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] >