--- name: unikit-gd-review description: >- Qualitative quality review of game design documents — answers "is this design good, and does it follow best practices?" — across all three GDD axes: systems, flows, and content types. Fans out adversarial lenses (completeness, clarity, pillar alignment, systems-math, fantasy-delivery, feasibility, scope) plus domain lenses that check it against the game-design rules, each prompted to find problems rather than validate; produces a severity-graded verdict and a two-bucket report (apply-ready fixes vs research), handed to /unikit-gd-apply or /unikit-gd-explore in one move. Scope is inferred: a named system, flow, or content type reviews that document; "all" runs a cross-document review. Use when the user wants a critique, quality judgment, or rules check of the design, e.g. "review the combat GDD", "review the onboarding flow". This is the subjective quality pass — for a mechanical consistency check (numbers, terms, IDs, references matching the registry) use /unikit-gd-verify. argument-hint: "[system name | SYS-slug | path | \"all\"] (scope inferred; no flags)" allowed-tools: - Read - Glob - Grep - Write - Edit - Bash(ls *) - Bash(find *) - Bash(wc *) - Bash(date *) - Bash(mkdir *) - Agent - AskUserQuestion disable-model-invocation: false user-invocable: true metadata: author: unikit version: "1.0" category: game-design --- # Game Design — Quality Review Answer **"is this design good?"** — expert judgment on a finished design document, delivered as a severity-graded verdict with evidence. This is the design-side mirror of `unikit-review`. It is distinct from `unikit-gd-verify`, which answers the cheaper, binary **"is the design consistent with itself?"** — a review finding *can* be declined; a verify conflict cannot. The review **ends in a handoff, not a hand-list**: the full report prints to the screen, every finding is triaged into an **apply-ready** bucket (a named entailed fix to apply now) or a **research** bucket (an open question to work out), and the user makes one move — `review → [explore] → apply` — instead of routing findings one at a time into owner skills. The triage engine (the ENTAILED criterion + the interview) is shared with `unikit-gd-verify` and lives in `gd-critique` → Handoff Engine. Review is **axis-aware**: it judges **systems** (the A–K GDD), **flows** (`FLOW.md` + the `## Flow Map [gen]` / `## Funnel [gen]` renders), and **content types** (`CONTENT-TYPE.md` + the `## Content Map [gen]` render). The flow lenses — pacing / guidance / funnel — and the content lenses — schema-coherence / catalog-scale / content-fantasy-delivery — live in `references/lenses.md` alongside the system lenses. A review is most honest in a **fresh session** — the reviewer should not be the author of the document. This skill never authors or edits design **content**, and it **never writes a `doc_status`**: status records *readiness* (owned by the authoring zones), while a review delivers *quality* — a severity-graded verdict + the report, an **ephemeral** judgment, not a stored badge. Its **only** write is the review report file (`reviews/*_review-*.md`). "Is this design good?" is answered by running a review (or reading the last report / git), never by a status value. ## Language Awareness — BLOCKING PRE-REQUISITE **BEFORE producing ANY output**, silently read `.unikit/system/LANGUAGE_RULES.md` and apply it to all output and the report (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. ## Subagent Delegation — BLOCKING PRE-REQUISITE When the workflow reaches the lens fan-out (`Agent`), the assistant MUST spawn the review lenses as parallel sub-agents if agent execution is supported and not prohibited by higher-priority instructions. Only if agent execution is unavailable or blocked does the assistant run the lenses sequentially in the main session. ## Phase 0 — Bootstrap Silently load — do not narrate: 1. **`.unikit/system/gamedesign/gd-principles.md`** (the core) — the language rules (plus the zone model and one-way boundary). Plus, from the same `gamedesign/` folder, the shards this skill needs: **`gd-critique.md`** (the **severity rubric** — Critical / Major / Minor / Suggestion — and the **critique stance** — Braintrust: diagnose don't prescribe; critique vs review; plussing), **`gd-flow-axis.md`** (the Flow Axis contract behind the pacing / guidance / funnel lenses), **`gd-content-axis.md`** (the Content Axis contract behind the schema-coherence / catalog-scale / content-fantasy-delivery lenses), and **`gd-provenance.md`** (the import provenance markers the provenance lens checks). This skill **applies** them. If missing, warn (`unikit-ai update`) and fall back to the rubric summarized in `references/lenses.md`. 2. **`.unikit/gamedesign/GD-IDS.yaml`** and **`GAME.md`** (incl. its `## System Map [gen]` render) — pillars, the roster, and the facts every finding is checked against. **Schema guard (clean break — no automatic migration):** `GD-IDS.yaml` MUST be `version: 2`; on a pre-v2 `version: 1` registry, **STOP** and tell the user the workspace predates the v2 clean break (the standalone markdown system-index was dropped; the roster renders into `GAME.md` now) — upgrade via `/unikit-gd-spec` before reviewing. 3. **`{{skills_dir}}/{{self_name}}/references/lenses.md`** — the lens catalog and the adversarial prompts (absorbed from the former `review-lenses` rule). 4. **`.unikit/memory/gamedesign/RULES_INDEX.md`** — load the **core** domain rules for the target's behaviour/domain (by `Load When`) so each domain lens has its theory: `economy`, `balance`, `progression`, `ux-onboarding`, `accessibility`, `monetization-ethics`, `liveops`, `frameworks`. 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. **One-way boundary:** never read `.unikit/code/`, project source, or build artifacts. **Single sanctioned exception:** the **feasibility lens** may read **only** `.unikit/DESCRIPTION.md` and `.unikit/ARCHITECTURE.md` (two files, exact paths) to flag implementability risks. It must NOT read `.unikit/code/`, `Assets/`, or any source/build artifact — doing so violates the one-way boundary. A feasibility finding cites the line it relied on in DESCRIPTION/ARCHITECTURE as its evidence. ## Phase 1 — Resolve Scope & Mode (no flags) **Scope** is a function of the prompt: 1. The argument names a system or a path → **single** review of that document. 2. The prompt says "all" / "all systems" / "все" → **cross** review of every `detailed` system. 3. Empty argument and several systems are detailed → **ask**: ``` AskUserQuestion: What should I review? Options: · All systems (cross-review) · None ``` **Mode** is the user's call — **critique** (iterate on a draft) or **review** (verdict on a finished document). Default to review on a `detailed` document; offer critique if the user is mid-authoring. Announce scope + mode in one line, then proceed. ## Phase 2 — Run the Lenses (adversarial fan-out) Select the lenses from `references/lenses.md`: the **core** lenses always (including **fantasy-delivery** — does section B's promised feeling actually arise from C/D/E, and is an SDT need served?), plus the **domain** lenses matching the system's behaviour/domain. When the system was built by import (its sections carry provenance markers — see `gd-provenance` → Provenance), also run the **provenance** lens over each `` section: inferred content is held to a stricter bar (≥ Major against source/registry) than author-sourced text. When the review **target is a `FLOW.md`** (or the scope is "all"), select the **flow lenses** (pacing / guidance / funnel) from `references/lenses.md` alongside the system lenses — a flow finding cites the `FLOW-` / `GOAL--` and the system `AC` / pillar it serves, on the same `RF--n` rubric. When the review **target is a `CONTENT-TYPE.md`** (or the scope is "all"), select the **content lenses** (schema-coherence / catalog-scale / content-fantasy-delivery) from `references/lenses.md` alongside the system lenses — a content finding cites the `CT-` / `CU--` and the `belongs_to` system / pillar it serves, on the same `RF--n` rubric. Run them as **2–4 parallel inline `Agent()`** calls, each given one lens, the configured **artifact language**, and the adversarial framing *"find what is wrong — do NOT validate"*. Each agent is **read-only** and returns findings only; it never writes. Fall back to running the lenses sequentially in this session if the Agent tool is unavailable. ``` Agent(subagent_type: general-purpose, model: sonnet, prompt: "Review through the lens. Your job is to FIND PROBLEMS, not validate. For each: severity (Critical/Major/Minor/Suggestion per the rubric), the document section, and the contradicted fact/pillar/rule as evidence. Diagnose — do not prescribe a fix. Return a findings list; write nothing. Write every finding in — this prompt is your only language source (you do not read Bootstrap or LANGUAGE_RULES), so translate domain concepts to their meaning (pacing→темп, exploit→лазейка, beacon→маяк); never transliterate jargon or code-switch mid-sentence. Keep only the id-tokens (RF-/SYS-/AC-/GOAL-/FORM-/CT-) and the lifecycle enum verbatim in English.") ``` Collect and de-duplicate the findings. Drop any finding with no section+evidence citation to **Suggestion** (`gd-critique`). **Flow lenses (active).** When the target is a `FLOW.md`, run the flow review lenses (pacing, guidance, funnel — does the wiring-mode deliver its intended arc, is each `GOAL` step guided, does the `## Funnel [gen]` measure the moments that matter?) from `references/lenses.md`, with the same adversarial framing. A `FLOW.md` **is** a review target; the lenses run over systems, flows, and `GAME.md`. **Content lenses (active).** When the target is a `CONTENT-TYPE.md`, run the content review lenses (schema-coherence, catalog-scale, content-fantasy-delivery — does `CT.fields` cover what the consuming system needs and are its types / `ref<>` right, is `bulk` vs `curated` the right call, does the catalog deliver the feeling section B promises?) from `references/lenses.md`, with the same adversarial framing. A `CONTENT-TYPE.md` **is** a review target; the lenses run over systems, flows, content types, and `GAME.md`. **Genre lens (active, declinable).** When `GAME.md` carries a `genre_profile:` id, run the genre **profile-completeness** lens (`references/lenses.md`): read that installed profile's `critical_sections` (`.unikit/system/gamedesign/genres/.json`) and ask whether each is present and filled across the docs under review — a missing genre-critical section is a **Major** (declinable / advisory — never a blocker). The profile's `review_emphasis` is an advisory **re-weight** of the lens priorities, not a new rubric. This is the **only** profile read on the design side — `unikit-gd-verify` stays genre-blind (it never reads `critical_sections`). No `genre_profile:` (universal baseline) → skip the lens. ## Phase 3 — Cross-Scope Checks (cross review only) When the scope is "all", add the cross-system lenses from `references/lenses.md`: formula compatibility, cross-AC consistency, pillar drift, total scope vs tiers, and **3–5 end-to-end "one moment through N systems"** scenarios. These are the checks no single-document review can make. **Depends symmetry is not a review lens** — `unikit-gd-verify` owns the Depends 3-way check (section F ↔ GD-IDS `depends_on` ↔ the `## System Map` Depends cell). ## Phase 4 — Verdict, Full Report (to screen) & Triage **Verdict.** Compute it from the findings: - **Single:** `APPROVED` (no Critical/Major) · `NEEDS REVISION` (Major, no Critical) · `MAJOR REVISION` (≥1 Critical). - **Cross:** `PASS` · `CONCERNS` · `FAIL` (≥1 Critical anywhere). **Ids.** Give each finding a **stable id** `RF--` (numbered in severity order, Critical first). The id is what a later `unikit-gd-apply` / `unikit-gd-system` edit cites in its changelog — it must survive the handoff. **Print the full report to the screen.** Render the *whole* findings table, the verdict line, and the "I like" calibration to the screen — not a one-line summary. (Printing only a summary and burying the report in a file was the complaint this fixes.) The file below is the *durable* copy of the same content; the screen is the *primary* surface. **Triage into two buckets** — the handoff engine (`gd-critique` → Handoff Engine), shared with `unikit-gd-verify`. Sort every finding by the silent **ENTAILED** criterion: - **Entailed** (all five points hold) → **apply-ready** automatically; record the one named fix. - **Not entailed** → the **interview pool**. Then run the **interview** (Braintrust — the user decides). Offer one **per-run** choice up front — **[Run the interview]** or **[Send everything to research]** — then, when interviewing, batch the pool through `AskUserQuestion` (**≤ 4 findings per call**). Per finding: **[I decide: ]** → apply-ready · **[To research]** → research · **[Decline]** → dropped. The interview **only classifies** and records the decision text; it **writes nothing** to the GDD (review stays non-authoring). A finding whose fix the user already holds in their head lands in apply-ready directly — no detour through `unikit-gd-explore`. **Write `.unikit/gamedesign/reviews/_review-.md`** (`mkdir -p` the `reviews/` dir; `` is the SYS-slug or `all`) with the **two explicit buckets** — this is the durable handoff interface (`unikit-gd-apply` reads apply-ready, `unikit-gd-explore` reads research): ```markdown # Review: — > Verdict: > Scope signal: · Mode: ## Findings | RF | Severity | Document / Section | Lens | Diagnosis (problem + evidence) | |----|----------|--------------------|------|--------------------------------| | RF--1 | Critical | SYS-combat / D | systems-math | FORM-damage output contradicts PIL-2's design test | ## Apply-ready ← hand to /unikit-gd-apply -n · · Fix (entailed): `. Empty bucket is valid — write "(none)".> ## Research ← hand to /unikit-gd-explore -n · `. Empty bucket is valid — write "(none)".> ## I like ``` The two buckets **replace** the old `Required before implementation` / `Suggestions` split and are **orthogonal to severity**: severity stays a column in the Findings table (the blocking-vs-non-blocking discipline still holds there); the buckets sort by *who acts* — the rule applies an entailed fix, the user decides the rest. A **clean** review (zero findings) still writes the report (the audit trail) with both buckets `(none)`, and **skips the handoff** (Phase 6) entirely — verdict only. ## Phase 5 — No status write (the verdict is ephemeral) `unikit-gd-review` **writes no `doc_status`** — it is **not** a status writer (it was the former writer of the dropped `reviewed` status; that status no longer exists). The verdict is a **quality** judgment, ephemeral by design: it lives in the printed report + the durable report file + git, **never** in a stored badge. A `detailed` document stays `detailed` through a review — quality is re-checked by **re-running** the review, not read off a status. Status records *readiness* and is owned by the authoring zones (`unikit-gd-system` / `unikit-gd-flow` / `unikit-gd-content`). A review never auto-applies fixes — the handoff (Phase 6) hands the apply-ready bucket to `unikit-gd-apply` and the research bucket to `unikit-gd-explore`, in one move, instead of routing revisions one finding at a time into the owning zones. ## Phase 6 — Handoff (only when there are findings) The review's job ends at the **diagnosis**; this phase hands the two buckets to the skills that act on them so the user makes **one** move — `review → [explore] → apply` — instead of routing findings one at a time into owner skills. **Safeguard — never decide alone.** When the **apply-ready** bucket is non-empty, first **show the apply-ready edits** on screen and let the user confirm or adjust them (the entailed fixes were sorted by the rule, but the user owns the call). Then: ``` AskUserQuestion: apply-ready fix(es) are ready. Apply them now? Options: 1. Apply now — runs /unikit-gd-apply on the apply-ready bucket, then verify 2. Not now — I'll read the file first ``` **Hand off — recommend-only (never a `Skill` call).** Neither `unikit-gd-review` nor `unikit-gd-verify` carries `Skill` in `allowed-tools`; each **prints** the `/unikit-gd-apply` recommendation for the user to run, and on Codex the auto-invoke nudge runs it — the two handoff tails are identical by contract. ### Auto-invoke the handoff — BLOCKING PRE-REQUISITE When this phase prints the `/unikit-gd-apply` recommendation, automatically invoke it (`$unikit-gd-apply `) rather than asking the user to run it by hand — the printed command is the recommend-only fallback for agents without auto-invocation. This is a single handoff, not a per-finding dispatch: invoke `unikit-gd-apply` once with the review file and let it route the apply-ready bucket to the owners. - **Apply now → yes:** print the apply command for the review file — ``` /unikit-gd-apply .unikit/gamedesign/reviews/_review-.md ``` `unikit-gd-apply` reads the **apply-ready** bucket as its deltas, dispatches them to the owning zones, and closes with one verify pass. Then **recommend** `/unikit-gd-explore ` for the **research** bucket. - **Apply now → no:** give **two recommendations** — `/unikit-gd-apply ` (apply-ready) and `/unikit-gd-explore ` (research) — for the user to run when ready. - **apply-ready empty** (the common case for a single subjective review): **skip the apply offer** — recommend only `/unikit-gd-explore ` (research). - A **single-zone** apply-ready set still goes through `/unikit-gd-apply`: its own GATE 2 bounces a lone zone straight to that owner — this skill never pre-routes. ## Final: Compact Report & Next Steps Follow the **Handoff Tail contract** (`gd-critique` → Handoff Engine): the runnable command is the **last block** on screen. Print the report and any note first, then close with **one** icon-prefixed command on its own line — nothing after it. Print the compact report: ``` Scope: Mode: Verdict: Findings: Critical · Major · Minor · Suggestion Buckets: apply-ready · research Report: .unikit/gamedesign/reviews/_review-.md ``` If the same finding recurs across reviews of different systems, note it **here** (above the command) as a candidate **studio `library` rule** (`/unikit-memory --module gamedesign`) so the lesson is captured as durable domain knowledge, not re-discovered each review. No summary document beyond the report file. **Then end with the handoff as the LAST block** — one command, following the pipeline `review → [explore] → apply`. Pick the single tail from the bucket state: - **research non-empty** → `🔎 /unikit-gd-explore ` - **research empty, apply-ready non-empty** → `🛠️ /unikit-gd-apply ` - **clean (no findings)** → `✅ /unikit-gd-verify ` Nothing prints after the command line — no verdict recap, no description of what the called skill does next. ## Ownership Boundaries - **Owns:** `.unikit/gamedesign/reviews/` report files — including the **triage** (every finding sorted into the apply-ready / research bucket). review writes **no** `doc_status` and edits **no** GDD content — the report file is its only write. The report is a **living pipeline artifact**: `unikit-gd-explore` is sanctioned to mutate it **in place** — promoting a developed `## Research` finding into `## Apply-ready` (research-bucket mode) — so the pipeline `review → [explore] → apply` runs on the one file. That cross-skill write is explore's only write to this folder. - **Read-only:** every design document (sections A–K, `GAME.md`, all of `GD-IDS.yaml` including `doc_status`); plus `DESCRIPTION.md`/`ARCHITECTURE.md` for the feasibility lens only. review makes **no** design-surface write — only the report file. - **Not this skill:** consistency/impact checks → `unikit-gd-verify`; **applying** the apply-ready bucket → `unikit-gd-apply`; **developing** the research bucket → `unikit-gd-explore`; authoring → `unikit-gd-system` (systems) / `unikit-gd-spec` (`GAME.md`). The handoff to apply/explore is **recommend-only** — this skill prints the command, it never invokes it. - **Never:** edit design **content** (any section A–K, `GAME.md`, or a `GD-IDS.yaml` fact value); write a `doc_status` (review is not a status writer); prescribe a fix the user did not ask for; inflate severity past the evidence; carry `Skill` in `allowed-tools` or apply a fix / invoke `unikit-gd-apply` itself (the handoff is a printed recommendation); read the code workspace beyond the feasibility exception. ## Quick Reference ``` /unikit-gd-review SYS-combat → single review → verdict + report (apply-ready + research buckets) → handoff /unikit-gd-review combat → resolve to the SYS-slug; same flow /unikit-gd-review all systems → cross-review with end-to-end checks → buckets → handoff /unikit-gd-review systems/SYS-combat.md → review a specific document path # handoff (recommend-only print): /unikit-gd-apply (apply-ready) · /unikit-gd-explore (research) ```