/game-docs

name: game-docs
description: >
  Writes and maintains a game's design docs: a one-page GDD with a feature index and short feature
  notes, kept true to the code by a link and status checker. Use for "draft a GDD", "spec out this
  mechanic", or updating docs after a playtest or code change. Not for building a game when no
  docs were asked for (`prototype-fast`, `game-jam`), READMEs or level layouts (`level-design`).

Game docs

Keep a game's design written down in as few words as will stay true. The GDD is one page that says what the game is and maps its features; each feature's detail lives in its own short note; and every number in the docs matches the code. Docs nobody keeps current are worse than none, so write less, edit in place, and sync after every change.

When to use

Run only when the user asked for game design docs, or when the project already has a GDD and a feature is being designed, changed, built or cut. A request to build a game or a feature is not a request for docs: let the engine and genre skills build it (through `$router`) and offer docs in one line at the end. Level layouts go to `$level-design`; READMEs, API docs and code comments are not this skill's job.

Workflow

1. **Look before writing.**

• Find the existing docs: `GDD.md`, `*design*`, `*spec*`, `docs/`, `design/`, a wiki folder, `specs/` (GitHub spec-kit) or `.kiro/specs/` (Kiro). Keep their folder, file names, language and format.
• Read the conversation (a planning chat is your main source) and, when code exists, the repo and `git diff`/`git log`. Never ask what the repo or the chat already answers.
• Sort the project into one of three cases. This decides everything below:
• **No GDD.** Only a request for a GDD starts one.
• **A GDD in this layout** (a feature index plus `features/<slug>/design.md`). Use the modes as written.
• **A GDD in any other form** (one long file, a wiki page, spec-tool folders). **Edit it in place, in its own format.** Make the smallest edit, in the user's style. Don't add an index, folders or headers to it, and don't suggest restructuring unless the user asks (mode E).

2. **Pick the mode** and read its section in [references/workflow-modes.md](references/workflow-modes.md):

| The user wants | Mode | |---|---| | a GDD, and there is none | **A. Draft the GDD** | | a new feature written up | **B. New feature** | | a feature changed after a playtest, tuning, rework or cut | **C. Change a feature** | | the docs to match code that was just written or changed | **D. Sync after coding** | | an existing GDD split into this layout (asked for explicitly) | **E. Migrate** | | a design decision recorded | **F. Record a decision** (also inside every other mode) |

3. **Write.** Use the template for the doc you are creating and [references/doc-rules.md](references/doc-rules.md) for where each fact lives, decision rows and proof annotations. Change existing docs with small edits to the affected section; don't regenerate a whole doc, because the user's own wording is part of the design. 4. **Verify.** Run the checker on the docs folder (paths are relative to this skill's folder; use `python` where `python3` doesn't exist):

   python3 scripts/check_docs.py <project>/docs
   python3 scripts/check_docs.py <project>/design --gdd game-design.md   # GDD under another name

Exit 0: no errors. Exit 1: fix each `ERROR`, and each `WARNING` that is real; say why the others don't apply. Exit 2: wrong folder or `--gdd` name. A `NOTE gdd-no-index` means the GDD is not in this layout; that is fine, so leave its structure alone. Then reread every number you touched against its source (the code, the diff or the user's message). 5. **Hand off** in a few lines: the docs created or changed (as links, or the diff for a small edit), the substance in 2 to 4 lines, the `[ASSUMPTION]`s and the questions that really matter, and decisions logged or statuses changed. Add a next step only if it isn't obvious. No to-dos or offers of more docs unless the user asked. Don't commit unless asked.

What to write, and when

| Moment | Write | |---|---| | The user asks for a GDD | `GDD.md` from the template, about one page, with the real design in it, plus a `design.md` with a concrete first proposal (rules and starting numbers, `[ASSUMPTION]`-marked) for the 2 or 3 features the core loop needs. Other features are index rows with status `idea` | | A feature is designed | its `features/<slug>/design.md` | | A feature first gets code (status `in progress`) | its `implementation.md` and `testing.md`, short, written against the real code | | Code that several features share appears (save format, event bus, scene flow) | `ARCHITECTURE.md`. Until then, one line in the GDD summary names the engine |

Write more only when the user asks for it. A plan for code that doesn't exist yet goes stale before the engine is chosen, so it is not written by default.

**Statuses**, the same words everywhere: `idea` → `designed` → `in progress` (code has started) → `implemented`, plus `changed — code pending` and `cut`. A feature's status lives in two places, the GDD index and `design.md`'s `**Status:**` header, and they must agree.

**Questions.** Ask at most one short round before the first draft, and none when the user said "just draft it" or already gave the answers. Ask only what you must not guess: the core fantasy (what the player does and feels), the audience and the platform, plus anything that blocks the draft. Number the questions, give each 2 to 4 options with your recommendation first, and say shorthand answers are fine ("1b, 2: PC only"). Fill every other gap with a sensible default marked `[ASSUMPTION]` and list the open questions in the handoff, where answering them costs the user nothing.

Gotchas

• **"Draft a GDD" produced 20+ files.** Writing a design note, an implementation plan and a test plan for every MVP feature, plus an ARCHITECTURE.md, bef