Immutable. This exact content is served forever at /api/v1/blob/16612ad5d59def1e.
---
name: unikit-gd-system
description: >-
Author and own ONE system's design document (the A–K SYSTEM GDD) at
.unikit/gamedesign/systems/SYS-<slug>.md — the depth layer of the GDD, single-system
scope. Create the skeleton and walk the collaborative section-cycle to write its
parameters, rules, formulas, and acceptance criteria ("detail the combat system",
"write the GDD for the inventory system", "fill in the rest of this system doc",
"spec out the parameters of X"), AND revise it after approval under the delta discipline
("raise the damage by 10%", "tune the economy", "rework the status system", "nerf
X", "change this rule") — a number change is Tuning, a small rule a Tweak, restructuring
a Rework; each bumps the version and logs the delta. To add a NEW system or
restructure the system map use /unikit-gd-spec; to edit GAME.md content use /unikit-gd-spec;
the moment an edit also touches a second system, a content type, a flow, or GAME.md (two
or more zones) use /unikit-gd-apply; to invent a brand-new game concept use
/unikit-gd-brainstorm.
argument-hint: "<system name | SYS-slug> [\"<what to change>\"] (mode inferred from doc state + intent; no flags)"
allowed-tools:
- Read
- Write
- Edit
- Glob
- Grep
- Bash(ls *)
- Bash(find *)
- Bash(wc *)
- Bash(date *)
- AskUserQuestion
disable-model-invocation: false
user-invocable: true
metadata:
author: unikit
version: "1.0"
category: game-design
---
# Game Design — Per-System GDD (Authoring & Revision)
Own **one system's design document** at
`.unikit/gamedesign/systems/SYS-<slug>.md` — eleven sections (A–K) plus any
domain section-packs. This skill owns the **system zone** (`gd-principles` → Zone
Ownership): the **full lifecycle** of a `SYSTEM.md` lives here — **create** the
skeleton, **fill** its placeholders, and **revise** approved content (Tuning /
Tweak / Rework) under the delta discipline. There is no separate editor skill.
It never creates the master spec or the map, and never edits `GAME.md` content —
that is `unikit-gd-spec`; player-action flows are `unikit-gd-flow`'s.
## Language Awareness — BLOCKING PRE-REQUISITE
**BEFORE producing ANY output**, silently read `.unikit/system/LANGUAGE_RULES.md`
and apply it to all output and artifacts (fall back to English if it is missing) —
including the rule to **translate concepts, not transliterate jargon**.
`gd-principles` → "Language" adds the game-design specifics: which IDs and stored
field values stay English. Do not announce the language setting.
## Phase 0 — Bootstrap
Silently load — do not narrate:
1. **`.unikit/system/gamedesign/gd-principles.md`** (the core) — the collaborative
protocol, the facts registry / ID conventions, and the language rules. Plus, from
the same `gamedesign/` folder, the shards this skill needs: **`gd-authoring.md`**
(the **section-cycle authoring contract** + the **delta discipline** — the
mandatory Version +1 → changelog → registry-check → recommend-verify tail),
**`gd-lifecycle.md`** (the lifecycle & status spine), and **`gd-provenance.md`**
(the import provenance markers). This skill **applies** that contract; it does not
restate the mechanics. If missing, warn (`unikit-ai update`) and fall back to the
protocol as summarized in this file.
2. **`.unikit/gamedesign/GAME.md`** — pillars, loops, non-goals the system must
serve (its roster is in `## System Map [gen]`). If it does not exist, **stop** —
there is no master spec yet. Read `.unikit/gamedesign/concepts/INDEX.md` (if it
exists) to route precisely: a `drafted`/`approved` concept present → recommend
`/unikit-gd-spec` (build the master spec from it); no concept — or no
`concepts/INDEX.md` (or no `concepts/` dir) at all → recommend
`/unikit-gd-brainstorm` first, then `/unikit-gd-spec`.
3. **`.unikit/gamedesign/GD-IDS.yaml`** — find the target system's entry under
`systems`. If there is **no entry**, the system is not on the map: offer to add
it via `/unikit-gd-spec` (**add-system** — graft this one system onto the map, not
a remap), or pick an existing `not-started` system. Do not author an off-map
system.
4. **`.unikit/memory/gamedesign/RULES_INDEX.md`** — load the **core** domain
rules for this system's **behavioural domain**, on demand by `Load When`, plus
any studio `library` rule on the same topic. Read the domain from the system's
name and Overview (the behaviour it drives), **not** from the coarse GD-IDS
`category`. When the behaviour is **unambiguous**, attach the matching domain
automatically (its section-pack rides along — auto-attached with a veto, see item 6
and Phase 4); when it is **ambiguous** or the category is coarse (Gameplay / Meta),
settle it with one plain `AskUserQuestion` — framed as an outcome, no codes — rather
than guessing. A system may match more than one domain; they combine:
| Domain | Core rules to load | Section-pack |
|--------|--------------------|--------------|
| combat / mechanics | `balance`, `frameworks` | combat |
| ai-behavior | `balance`, `frameworks` | ai-behavior |
| economy / loot | `economy`, `balance` | economy |
| progression / unlock | `progression`, `balance` | progression |
| level / content | `level-design` | levels |
| narrative / dialogue | `narrative` | narrative |
| ui / onboarding | `ux-onboarding` | ux |
| liveops / events | `liveops`, `economy` | liveops |
| persistence | `progression` | persistence |
| monetization | `monetization-ethics`, `economy` | monetization |
| meta / other | `frameworks`, `core-loops` | — |
Every system also touches **accessibility** (section J) — load `accessibility`
when authoring J. Obey the index's **Rule-Loading Discipline**: load by `Load When`,
load a reference only from its parent rule's `> **References**:`, and **never glob the
memory tree** (`.unikit/memory/gamedesign/**`) to discover rules.
5. **`.unikit/RULES.md`** (if present) — project overrides, highest priority.
6. **`{{skills_dir}}/{{self_name}}/references/section-packs.md`** — the catalog of
domain section-packs. On an **unambiguous** domain the matching pack is
**auto-attached** — announced to the user in one outcome-language phrase (what it
adds for the player / the design, never the word "pack" or a code) that they can
veto; on an **ambiguous** domain a single plain Yes/No decides it. Never a mandatory
pass after section K, never surfaced as registry jargon. Load the pack named in the
table above (when one applies).
7. **Schema guard (clean break — no automatic migration).** `GD-IDS.yaml` MUST be
`version: 2`. If it is still `version: 1`, **STOP** and report: the design
workspace is on the pre-v2 layout — v2 dropped the standalone markdown
system-index and now renders the roster into `GAME.md` (`## System Map [gen]`);
there is no automatic migration. Tell the user to bump `GD-IDS.yaml` to
`version: 2` and fold the legacy system-index rows into GAME.md's
`## System Map [gen]` before re-running.
**One-way boundary:** never read `.unikit/code/`, project source, or build
artifacts. The only external read is `SOURCE.md` during an import (Phase 1).
## Phase 1 — Context
Gather the facts the system must stay consistent with (read-only):
- **Known facts** from `GD-IDS.yaml` — pillars (`implements` targets), entities,
formulas, and terms already locked by other systems. These are constraints, not
suggestions.
- **Neighbor GDDs** — for each system this one depends on (from the GD-IDS
`depends_on`, rendered in GAME.md `## System Map`), read its header and sections
**D (Formulas)** and **F (Dependencies)** to match data interfaces.
- **Recent `unikit-gd-verify` reports** for this system, if any
(`.unikit/gamedesign/reviews/`).
- **Import source** — if `GD-IDS`/GAME mention an import, or a
`researches/<date>_import-*/SOURCE.md` covers this system, read it: section
content is **extracted** from it, not regenerated. Mark provenance per
`gd-provenance` → Provenance: place `<!-- provenance: extracted from SOURCE.md -->`
under each section lifted from the source and `<!-- provenance: generated -->`
under each section inferred to complete the skeleton; untagged sections are
normal authored content.
- **Explore research (internal design lens)** — if this system was grafted from an
`unikit-gd-explore` brief, discover the research **deterministically** (survives a
`/clear`): read the system's `GD-IDS` `research:` pointer (authoritative), falling
back to the `researches/INDEX.md` entry whose `Target:` is this `SYS-<slug>`. Read
that research's `RESEARCH_BRIEF.md` → **`## New Feature Plan`** block and use its
**section seeds** as the *starting drafts* — a **seeded** section is **drafted
silently** in Generation (Phase 4) and confirmed in the group review (Phase 5); a
seed is a draft, not an approved write. For
a **revision** (Edit), the matching block is **`## Improvement Plan`** — its
ready-to-apply delta lines (`<Section>: <old> → <new>`), expected scale, touched
facts, and any `RF-<date>-n` it closes pre-fill the change set (the user still
approves every edit). These explore-seeded drafts are **untagged normal authored
content** — do **not** mark them `extracted` / `generated` (those markers are for
**imports** only; this is the generalization of import-reading stated canonically
in `gd-provenance` → Provenance, which this skill applies rather than restates).
## Phase 2 — Resolve Mode + Depth (no flags)
Check `.unikit/gamedesign/systems/SYS-<slug>.md` and read the intent in the prompt:
1. **Does not exist** → **Create**: build the skeleton (Phase 3), then author from
section A.
2. **Exists** and the prompt describes a **change to approved content** (a value,
rule, or structure: "raise damage", "tune the economy", "rework the status
system", "nerf X", "change this rule") → **Edit**: classify the scale and apply
the delta (Revision below). Approved text is changed **only** through this path.
3. **Exists with `[To be designed]` placeholders** and the intent is to continue /
fill (or no change is described) → **Fill**: resume from the remaining placeholders.
Approved text is **never overwritten** — only placeholders are filled. Skip the
skeleton sub-step (Phase 3.1); still fork-scan and run Phases 4–5 over the
placeholders.
4. **Exists, complete, no change described** → detailing is done; nothing to author.
Offer review / verify (Phase 6) and stop.
If the system name is ambiguous (matches several entries, or none) →
`AskUserQuestion` listing candidates. Never guess the target.
**Depth gate (Create / Fill only).** Once the mode is Create or Fill, present **one**
depth picker — the named tiers `core/standard/full`, each with what it adds, not bare
letters:
```
AskUserQuestion: How deep should this pass go?
Options:
1. core (recommended) — the floor that gets the doc to a solid, usable base: Overview,
Player Fantasy, Detailed Design, Formulas, Acceptance Criteria.
2. standard — core + Edge Cases, Dependencies, Tuning Knobs, Telemetry, Accessibility.
3. full — every section + the relevant domain pack(s).
```
The picked tier is the **ephemeral scope of this pass — NOT stored** (`gd-authoring` /
`gd-lifecycle`); the lasting fact is the inferred status at Phase 6. The matching
**section-pack** for the system's domain (Phase 0 table) is **auto-attached when the
domain is unambiguous** — announced in one outcome-language phrase you can veto; an
ambiguous domain gets a single plain Yes/No in the Phase 4 decision round. **Edit** mode
skips the depth gate entirely (it lies flat on the Revision flow).
---
## Load the Mode Body
With the mode resolved (Phase 2) and the depth picked (Create / Fill only), load the
matching body on demand and follow it — do **not** keep both bodies in context. Each
returns to **Phase 6** (Final) below.
| Mode | Reference body |
|------|----------------|
| **Create / Fill** | `{{skills_dir}}/{{self_name}}/references/mode-author.md` — the Decision-First section-cycle: the A–K section map + core-set, Phase 3 (Skeleton + Fork-Scan), Phase 4 (Decision Interview + Generation), Phase 5 (Group Review). |
| **Edit** | `{{skills_dir}}/{{self_name}}/references/mode-revise.md` — classify the scale (Tuning / Tweak / Rework / Structural-redirect), apply the change, then the mandatory delta tail. |
---
## Phase 6 — Final: Registry & State + Handoff
### Registry & State (Create / Fill)
After the sections are authored and accepted:
1. **Scan the GDD** for registry candidates — entities, formulas, and constants
referenced in **two or more places** (within this doc or cross-system). Internal
single-use values stay in the GDD.
2. Present a **NEW / KNOWN** summary and get approval to write `GD-IDS.yaml`
(`entities`, `formulas`, plus the `systems` entry's `doc_status` / `version`).
Existing values are never changed silently; every fact carries its `source`.
3. **Status (inferred — `gd-lifecycle`).** Set the system's status in the **two places
that must agree** — the `SYSTEM.md` header `> Status:` token (inside the combined
header line, not a separate bold line) and the `GD-IDS.yaml` `doc_status`:
- `detailed` once the whole **core-set (A/B/C/D/H)** is authored.
- **held at `skeleton`** while any **core** section carries `<!-- deferred -->` (the
soft floor guard; the WARN in Phase 4) — the status does **not** rise to
`detailed`.
- when the core is complete but ≥1 **non-core** section is deferred, the status is
`detailed` and the `## System Map [gen]` renders it `detailed · partial (n/m)`
(inferred from the markers, never a stored field).
Set `version: 1` in `GD-IDS.yaml` (and the header), write the initial changelog
block to section K (`#### v1 — <date> — initial design` with the
`AC: + AC-<slug>-1 … N (new)` line) — the single current block (K1).
The `## System Map [gen]` renders this system's status/version (incl. the `· partial`
suffix) **read-only** from `GD-IDS`; it is **not** this skill's surface — it
re-renders on the next `unikit-gd-verify` freshness check or `unikit-gd-spec` touch
(`gd-lifecycle` → Lifecycle & Status). Recommending verify (below) closes that loop.
### Handoff
Recommend the next steps (do not auto-invoke):
- ✅ Verify consistency & impact — /unikit-gd-verify SYS-<slug>
- 🔍 Qualitative review (fresh session) — /unikit-gd-review systems/SYS-<slug>.md
- 🧩 Detail the next system — /unikit-gd-system <SYS-slug>
A review is most independent in a **fresh session** (the reviewer should not have
authored the doc). `unikit-gd-verify` checks the doc against the registry, flags
dependent systems, and refreshes the `## System Map [gen]`.
## Final: Compact Report
The terminal plaque (TIER A — `gd-principles` → Language): lead with the **name**; the
`SYS-` / `AC-` ids ride along as parenthetical copy-paste tags; render the lifecycle
status as a **plain phrase**, never the raw enum.
```
System: <name> (SYS-<slug>)
Mode: <create | fill | edit (tuning|tweak|rework)> · Depth: <core | standard | full> (create/fill)
Doc: .unikit/gamedesign/systems/SYS-<slug>.md — <ready | ready, a couple of optional blocks left | skeleton, main blocks not filled yet | updated, awaiting re-review>, vN
Sections authored/edited: <the named list> [deferred: <names carrying <!-- deferred --> > | none]
Registry: +<E> entities, +<F> formulas, +<T> terms (GD-IDS.yaml)
Acceptance criteria: AC-<slug>-1 … AC-<slug>-N [AC delta on an edit: +<n> / changed <n> / removed <n>]
```
No summary document, no report file.
## Ownership Boundaries
- **Owns:** the **full lifecycle** of `systems/SYS-<slug>.md` — creating the
skeleton, filling placeholders, **and revising approved content** (Tuning / Tweak
/ Rework, with the version bump + changelog + `revised` status); the system's
`GD-IDS.yaml` facts (`entities`, `formulas`, `terms`) and its `doc_status` /
`version`.
- **Not this skill:** `GAME.md` content **or** structure / the system map →
`unikit-gd-spec`; player-action flows → `unikit-gd-flow`; quality verdicts →
`unikit-gd-review`; consistency & impact (and the `## System Map [gen]` freshness
render) → `unikit-gd-verify`.
- **Never:** write, fill, or edit without approval; overwrite approved text outside
the delta discipline; skip the version bump or changelog on an edit (unrecorded
delta); change a `GD-IDS.yaml` value silently; delete or renumber an ID; touch
structure or `GAME.md`; read the code workspace or project source.
## Quick Reference
```
/unikit-gd-system SYS-combat → create skeleton + author A–K (if no doc yet)
/unikit-gd-system combat → resolve to the SYS-slug; same flow
/unikit-gd-system SYS-combat → resume filling placeholders (partial doc)
/unikit-gd-system SYS-combat "raise grunt damage 10%" → Tuning: edit G/C, one approval
/unikit-gd-system combat "small fix to the parry rule" → Tweak: targeted edit
/unikit-gd-system SYS-combat "rework the status system" → Rework: section-cycle old-vs-new
```