# GDD Structure & Right-Sizing

A GDD's job is to get read and used, not to be exhaustive. Pick the right size before picking the sections.

## Which size to use

| Size | When | Length |
|---|---|---|
| **One-pager / pitch doc** | Early concept, pitching to a publisher/team lead, internal greenlight | High concept, pillars, core loop, hook, target audience/platform, comparable titles. ~1 page. |
| **Lean GDD** | Most indie/small-team projects, vertical slices | Adds: detailed core loop breakdown, primary systems (not exhaustive), progression overview, art/audio direction notes, scope/milestones. ~5-15 pages. |
| **Full GDD** | Larger teams, publisher-facing, complex systems that need shared source of truth | Every section below, fully detailed, often split into separate system-specific docs linked from a master doc. |
| **Systems-only spec** | User just wants one system nailed down (e.g. "write up the crafting system") | Skip the rest of this file — go straight to the relevant pattern in `systems-design-patterns.md` and write a focused spec: goal, player-facing rules, edge cases, open questions. |

Default to **lean GDD** unless the user's request or stated team size clearly calls for more or less.

## Full section list (use what's relevant, cut the rest)

1. **High Concept** — one sentence. What is this game, in genre-comparison shorthand if useful ("X meets Y").
2. **Pillars** — 3-4 design pillars that every feature decision gets checked against. Concrete, not generic ("readable chaos in combat," not "fun gameplay").
3. **Target Audience & Platform** — who, and where they'll play it. Drives UI scale, session length assumptions, monetization model if any.
4. **Core Gameplay Loop** — the verb loop the player repeats minute-to-minute, and how it nests into a session-level loop and a meta/long-term loop. Diagram this as a simple cycle if it helps (explore → fight → loot → upgrade → repeat).
5. **Mechanics** — the verbs themselves: what the player can do, moment to moment. Keep this to player-facing rules, not implementation.
6. **Systems** — the underlying machinery: combat system, progression system, economy, crafting, AI behavior, etc. Each gets its own subsection or its own doc once it's non-trivial — point to `systems-design-patterns.md`.
7. **Progression** — how player power/unlocks/narrative reveal unfolds over the full game. Pacing of new mechanics, not just numeric power.
8. **Level/World Design** — structure (linear, hub-and-spoke, open world), how levels teach and escalate. See the Stage 5 guidance in the main skill file.
9. **Narrative & World** — setting, tone, story structure, how much story is delivered vs. emergent. Skip or keep minimal for mechanically-driven games.
10. **UI/UX** — key screens, HUD philosophy, accessibility considerations (colorblind modes, remappable controls, difficulty options).
11. **Art & Audio Direction** — mood references, visual style pillars, audio's role (diegetic feedback, music adaptivity). Light touch unless the user is the art/audio lead.
12. **Monetization** (if F2P/mobile) — currency types, what's sold, what's earnable, and explicitly how monetization doesn't undercut the core pillars. Cross-reference the economy section in `systems-design-patterns.md`.
13. **Technical Considerations** — engine, platform constraints, anything that bounds design choices (e.g. mobile thermal/battery limits, online vs. offline).
14. **Scope & Milestones** — what's in the vertical slice vs. full release; biggest risk items first.

## Writing conventions

- Player-facing language for mechanics ("the player can dodge-roll for 0.4s of i-frames"), not engineering language.
- Every section should answer "why" as much as "what" — tie back to pillars.
- Use tables for anything enumerable (enemy types, item tiers, currencies) rather than prose paragraphs.
- Flag open questions explicitly (`**Open question:**`) rather than silently picking an answer the user didn't ask for, when a decision has real design tradeoffs.