| name | t1k:designer:base:document |
| description | GDD structure, templates, and living documentation patterns for game projects — wiki pages, design docs, section layout, sync triggers |
| effort | medium |
| keywords | ["GDD","game design document","documentation","design"] |
| version | 1.12.0 |
| origin | theonekit-designer |
| repository | The1Studio/theonekit-designer |
| module | base |
| protected | false |
Game Design Document
When This Skill Triggers
- Creating or updating a GDD, wiki page, or design document
- New demo added to the project
- Major gameplay feature changed (combat, inventory, progression, UI)
- Design review requested; syncing docs to code
- Writing Demo-*.md wiki pages for DOTS-AI demos
What a GDD Is
A GDD (Game Design Document) is the living specification of a game's design intent. In this project, it exists at two levels:
- Demo Wiki Pages (
docs/wiki/Demo-{DemoName}.md) — per-demo, code-synced, <300 lines
- Full GDD — high-level design pillars, economy, balance, art direction
GDD Section Overview
| Section | Purpose |
|---|
| Game Overview | Title, genre, platform, audience, core loop |
| Game Pillars | 3-5 non-negotiable design tenets |
| Gameplay Mechanics | Core loop, combat, inventory, progression |
| Game Flow | Phase state machine, win/lose conditions |
| UI/UX Design | Screen layout, HUD, menu flow |
| Economy & Monetization | Currency, shops, drop rates |
| Technical Requirements | FPS target, memory budget, platform constraints |
| Art & Audio Direction | Visual style, palette, sound design |
| Content Matrix | Items, enemies, levels with stats |
| Balance Parameters | Tuning knobs, difficulty curves |
→ See references/gdd-template.md for full section templates
Demo Wiki Page Workflow
- Read
Editor/ (SceneSetup, PrefabCreator) to extract unit counts, arena sizes, menu paths
- Read
Runtime/ (Systems, Components) to extract class names, constants
- Read existing wiki page — identify stale sections
- Cross-reference with library/package code for accuracy
- Write/update using mandatory 14-section structure from
game-designer agent
- Verify ALL numbers match code constants (grep don't guess)
→ See references/demo-wiki-template.md for mandatory section list and examples
Trigger Conditions
| Event | Action |
|---|
| New demo implemented | Create docs/wiki/Demo-{Name}.md from template |
| Code changes (systems, components) | Update affected wiki sections |
| Stats/balance tuned | Update Content Matrix and Balance Parameters |
| UI redesigned | Update UI/UX Design section |
| New editor tool added | Update Editor Tools section |
| Library module added | Update Library Coverage section |
Living Doc Principles
- Code is source of truth — grep constants, never guess numbers
- Wiki mirrors code — update docs immediately after code changes
- Cross-reference, don't duplicate — link to other wiki pages
- Numbers must be verifiable — comment which file/line each constant comes from
→ See references/living-doc-patterns.md for sync patterns and cross-reference conventions
Common Mistakes
| # | Mistake | Fix |
|---|
| 1 | Hardcoded numbers in wiki that don't match code | Grep source constants before writing |
| 2 | Wiki over 300 lines | Extract deep-dives to Domain-*.md, link from wiki |
| 3 | Missing cross-reference updates | After any wiki change, search for pages that link to it |
| 4 | Stale system class names after rename | Run grep for old name, update all occurrences |
Cross-References
- engine implementation skills — library component and system names for accurate documentation
- engine architecture skills (auto-activated via registry) — system design patterns
- engine code convention skills (auto-activated via registry) — naming for mapping code to docs
Reference Files
| File | Coverage |
|---|
references/gdd-template.md | Full GDD with all standard sections and guidance |
references/living-doc-patterns.md | Sync triggers, cross-reference conventions, wiki patterns |
references/demo-wiki-template.md | Demo-*.md mandatory structure, how to gather info from code |
Gotchas
- GDD goes stale on day 2 of production — without a sync trigger (post-feature, post-playtest, post-pivot), the GDD becomes fiction. Bake the trigger into your sprint review.
- One-page GDDs work for prototypes; multi-page GDDs work for live games — a 60-page GDD for a 2-week prototype kills the prototype. Right-size by horizon.
- Wiki vs in-repo MD is a real fork — wiki updates outside PR review drift from code reality. Prefer in-repo docs for truth, wiki for marketing-facing summaries.
