GDD Writer

Maintains the Game Design Document at docs/design/<YYYY-MM-DD>-<slug>-gdd.md. Keeps design (what the game is and why) separate from implementation (how the code works).

Core rule: the GDD drives the code. If code diverges from the GDD, document the divergence in PROGRESS.md (or NOTES.md); never silently rewrite the GDD to match code.

File path convention

• Location: docs/design/
• Filename: <YYYY-MM-DD>-<slug>-gdd.md (date is the GDD's first-write date; slug is kebab-case of the working title).
• One GDD per project. On major scope rewrites, write a NEW dated file rather than editing the old one — keep the trail. The plan file (docs/plans/<YYYY-MM-DD>-<slug>-plan.md) references the GDD path.

Standard GDD sections

If no GDD exists, create one with these sections. Skip sections that don't apply to the genre.

Writing rules

• One section, one purpose. Don't mix mechanics into narrative.
• No code, no class names, no file paths. That belongs in CLAUDE.md or PROGRESS.md.
• Tables for structured data, bullets for lists, prose for fantasy/tone.
• Tag uncertain sections [HYPOTHESIS] until validated through playtesting.
• Numbers stay in the GDD for design intent (e.g. "player has 3 jumps"), exact tuning lives in .tres resources or constants.

Adding a new mechanic

Template:

## [HYPOTHESIS] {Mechanic Name}

One- to three-sentence description of what the mechanic is and why it exists.

**How it works:**
- What the player does / sees
- How it integrates with existing mechanics
- What decisions / consequences it creates

**Why this mechanic:**
Tie to design pillars. If it doesn't reinforce a pillar, cut it or revise the pillar.

**Risks:**
- What could break? Balance, feel, complexity creep?

**Implementation order:**
Where this fits in the roadmap. Before/after the core loop is solid?

Drop [HYPOTHESIS] once validated through playtesting.

Adding a content entry

Template (item, enemy, level — adapt fields):

**{Name}** — {Type}, {Tag/Element}, {key stats}
*"{Flavor text — one line, in the voice of the world}"*
{Role in gameplay in one sentence.}

Example:

**Frostfang Pendant** — Accessory, Ice, +15 AP, +5% crit
*"Cold to the touch, even in summer."*
Mid-game DPS amulet for ice mages — pairs with Glacier Strike.

Anti-patterns to avoid

Cross-references

After updating the GDD, check whether PROGRESS.md or CLAUDE.md need follow-up. The update-docs skill performs that cross-check.