design-system

User Guide

• When to use: Guided, section-by-section CDD authoring for a single module. Gathers context from existing docs, walks through each required section collaboratively, cross-references dependencies, and writes incrementally to file. Supports both game and general product domains.
• Inputs: Command arguments: /design-system <module-name> [--review full|lean|solo]; project artifacts referenced below; user decisions and approvals before writes.
• Outputs: Primary artifacts, reports, or conversation guidance described below; write files only after user approval.
• Memory-bank writes: None.
• Next steps: Follow the workflow hand-off or next-step guidance below; recommendations do not auto-run and require explicit user command/approval.

When this skill is invoked:

Domain detection. The concept document reveals the domain:

• 游戏专用: Read design/cdd/game-concept.md — concept contains game-specific sections (Core Loop, MDA analysis, player types) → use game CDD section names (Player Fantasy, Detailed Rules, Formulas, Tuning Knobs, Visual/Audio)
• 通用产品: Read design/cdd/product-concept.md — concept contains product-specific sections (User Journey, JTBD, user personas) → use product CDD section names (User Promise, Detailed Design, Data Model, Configuration, Integration)

Sections below are marked [通用场景], [游戏专用], or [通用产品].

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 standards/director-gates.md for the full check pattern.

A module name or retrofit path is required. If missing:

1. Check if design/cdd/module-index.md exists.
2. If it exists: read it, find the highest-priority module with status "Not Started" or equivalent, and use AskUserQuestion:
   • Prompt: "The next module in your design order is [module-name] ([priority] | [layer]). Start designing it?"
   • Options: [A] Yes — design [module-name] / [B] Pick a different module / [C] Stop here
   • If [A]: proceed with that module name. If [B]: ask which module to design (plain text). If [C]: exit.
3. If no module index exists, fail with:

   "Usage: /design-system <module-name> — e.g., /design-system movement Or to fill gaps in an existing CDD: /design-system retrofit design/cdd/[module-name].md No module index found. Run /map-systems first to map your modules 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/cdd/, enter retrofit mode:

1. Read the existing CDD 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/cdd/[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

• Concept document: Read the appropriate concept document based on domain:
  • 游戏专用: Read design/cdd/game-concept.md
  • 通用产品: Read design/cdd/product-concept.md

  If missing: "No concept document found. Run /brainstorm first."

• Module index: Read design/cdd/module-index.md — fail if missing:

  "No module index found at design/cdd/module-index.md. Run /map-systems first to map your modules."

• Target system: Find the system in the index. If not listed, warn:

  "[system-name] is not in the module 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 CDDs have already established and this CDD 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 module index, identify:

• Upstream dependencies: Systems this one depends on. Read their CDDs if they exist (these contain decisions this system must respect).
• Downstream dependents: Systems that depend on this one. Read their CDDs if they exist (these contain expectations this system must satisfy).

For each dependency CDD 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/cdd/game-pillars.md if it exists
• Existing CDD: Read design/cdd/[system-name].md if it exists (resume, don't restart from scratch)
• Related CDDs: Glob design/cdd/*.md and read any that are thematically related (e.g., if designing a system that overlaps with another in scope, read the related CDD 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 CDDs vs. undesigned]
• Depended on by: [list, noting which have CDDs vs. undesigned]
• Existing decisions to respect: [key constraints from dependency CDDs]
• Pillar alignment: [which pillar(s) this system primarily serves]
• Known cross-system facts (from registry):
  • [entity_name]: [attribute]=[value], [attribute]=[value] (owned by [source CDD])
  • [item_name]: [attribute]=[value], [attribute]=[value] (owned by [source CDD])
  • [formula_name]: variables=[list], output=[min–max] (owned by [source CDD])
  • [constant_name]: [value] [unit] (owned by [source CDD]) (These values are locked — if this CDD 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 CDD 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 technology context and surface any constraints or knowledge gaps that will shape the design. Use the detected domain from Phase 2.

[游戏专用] Step 1 — Determine the engine domain for this system: Map the system's category (from module-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 1 — Determine the stack domain for this module: Map the module's category (from module-index.md) to a stack domain:

Module Category	Stack Domain
Foundation/Infrastructure, config, logging, error handling	Framework / Runtime
API, web services, request handling	API Design / Framework
Data models, schemas, storage	Data Storage / ORM
Auth, permissions, security	Auth / Security
UI, frontend, user-facing interfaces	Frontend / UI
CLI, tooling, developer-facing	CLI / Distribution
Data pipelines, ETL, analytics	Data Pipeline / Analytics
Integration, webhooks, third-party APIs	Integration / Messaging
Performance, caching, optimization	Performance / Caching

[游戏专用] Step 2 — Read engine context (if available):

• Read standards/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 2 — Read stack context (if available):

• Read standards/technical-preferences.md to identify the language, framework, runtime, database, and pinned versions
• If stack reference docs are configured, read docs/reference/[stack]/VERSION.md
• Read docs/reference/[stack]/modules/[domain].md if it exists
• Read docs/reference/[stack]/breaking-changes.md for domain-relevant entries
• Glob docs/architecture/adr-*.md and read any ADRs whose domain matches (check the Technology 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 CDD]
  (or "None yet")

[通用产品] If stack reference docs exist, present before starting design:

## Technical Feasibility Brief: [Module Name]
Stack: [language] + [framework/runtime] [version]
Domain: [domain]

### Known Stack Capabilities (verified for [version])
- [capability relevant to this module]
- [capability 2]

### Stack Constraints That Will Shape This Design
- [constraint from stack reference or existing ADR]

### Knowledge Gaps (verify before committing to these)
- [post-cutoff framework/API behavior this design might rely on — mark HIGH/MEDIUM risk]

### Existing ADRs That Constrain This Module
- ADR-XXXX: [decision summary] — means [implication for this CDD]
  (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."

[通用产品] If no stack reference docs exist (stack not yet configured), show a short note:

"No technology stack 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 technology 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 CDD file with empty section headers. This ensures incremental writes have a target.

Use the inline skeleton below. Do not read an external CDD template file here; the former external game design document template has been folded into this skill.

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

[Product] For product CDDs, use this skeleton instead of the game skeleton above:

# [Module Name]

> **Status**: In Design

## Overview
[To be designed]

## User Promise
[To be designed]

## Detailed Design
### Core Specification
[To be designed]
### States and Transitions
[To be designed]
### Interactions with Other Modules
[To be designed]

## Data Model
[To be designed]

## Edge Cases
[To be designed]

## Dependencies
[To be designed]

## Configuration
[To be designed]

## Integration 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/cdd/[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] CDD
• Current section: Starting (skeleton created)
• File: design/cdd/[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 CDDs 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:

   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 CDD] 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 module's category, layer, and detected domain from the module 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.
• [通用产品] Framing tab: Foundation/Infrastructure layer → [A] recommended. User-facing categories (API, CLI, Workflow, UI, Integration) → [C] Both recommended.
• ADR ref tab: Glob docs/architecture/adr-*.md and grep for the system or module name in the CDD 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.
• [通用产品] User promise tab: Foundation/Infrastructure layer → [B] No recommended. User-facing modules → [A] Yes recommended.

Append (Recommended) to the appropriate option text in each tab.

Framing questions (ask BEFORE drafting): Use AskUserQuestion with a multi-tab widget selected by domain:

[游戏专用] Game 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 CDD 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

[通用产品] Product widget:

• Tab "Framing" — "How should the overview frame this module?" Options: [A] As a data/infrastructure layer (technical framing) / [B] Through its user-facing value (product framing) / [C] Both — describe the data layer and the user value it enables
• Tab "ADR ref" — "Should the overview reference the existing ADR for this module?" Options: [A] Yes — cite the ADR for implementation details / [B] No — keep the CDD at pure design level
• Tab "User Promise" — "Does this module have a user promise worth stating?" Options: [A] Yes — users experience it directly / [B] No — pure infrastructure, users experience 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)
• [通用产品] How does a user interact with this module? (API call / UI interaction / CLI command / automated process)
• [游戏专用] Why does this system exist — what would the game lose without it?
• [通用产品] Why does this module exist — what user value, workflow, API, CLI, or operational promise would the product lose without it?

Cross-reference: Check that the description aligns with how the module 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 in /architecture-decision, not the CDD. The CDD describes behavior; the ADR describes the technical approach used to achieve it.

---

Section B: Player Fantasy

Goal: The emotional target — what the player should feel.

Derive recommended option before building the widget: Read the system's category and layer from Phase 2 context:

• Player-facing categories (Combat, UI, Dialogue, Character, Animation, Audio, Level/World) → [A] Direct recommended
• Foundation/Infrastructure layer → [B] Indirect recommended
• Mixed categories (Camera/input, Economy, AI with visible player effects) → [C] Both recommended

Append (Recommended) to the appropriate option text.

Framing question (ask BEFORE drafting): Use AskUserQuestion:

• Prompt: "Is this system something the player engages with directly, or infrastructure they experience indirectly?"
• Options: [A] Direct — player actively uses or feels this system / [B] Indirect — player experiences the effects, not the system / [C] Both — has a direct interaction layer and infrastructure beneath it

Use the answer to frame the Player Fantasy section appropriately. Do NOT assume the answer.

Questions to ask:

• What emotion or power fantasy does this serve?
• What reference games nail this feeling? What specifically creates it?
• Is this a "system you love engaging with" or "infrastructure you don't notice"?

Cross-reference: Must align with the game pillars. If the system serves a pillar, quote the relevant pillar text.

Agent delegation (MANDATORY): After the framing answer is given but before drafting, spawn creative-director via Task:

• Provide: system name, framing answer (direct/indirect/both), game pillars, any reference games the user mentioned, the game concept summary
• Ask: "Shape the Player Fantasy for this system. What emotion or power fantasy should it serve? What player moment should we anchor to? What tone and language fits the game's established feeling? Be specific — give me 2-3 candidate framings."
• Collect the creative-director's framings and present them to the user alongside the draft.