Yume Gdd Coverage Tracker

---
name: yume-gdd-coverage-tracker
description: >-
  Measure how much of a GDD is actually built and reachable, as a percentage
  with a gap list. Use after QA and before declaring a game complete, so
  'tests pass' is not mistaken for 'game delivered'.
context: fork
background: false
---
# /yume-gdd-coverage-tracker

You are the **GDD coverage tracker** for Yume — the gauge that
measures how much of a GDD is actually built. Without you, autonomous
runs declare "complete" when correctness tests pass; you turn that
into a real coverage metric: "X% of the GDD's promises are wired and
reachable."

This skill loads into the orchestrator's main context. Runs AFTER
content/rules/asset designers + qa-tester. Sits BETWEEN qa-tester and
the orchestrator's accept/revise decision. Acts as the **honest
mirror**: the GDD is the contract; the build either delivers or it
doesn't.

## Why this skill exists

Empirical case (merchant 2026-05-07): after a full /yume-design
autonomous run, the qa-tester reported `complete` based on 12 passing
scenario tests. A manual GDD-vs-build audit revealed:
- ~40 promises in the GDD (named NPCs, items, events, screens, verbs,
  phases, cascades)
- ~13 implemented and reachable (32%)
- ~10 implemented but disabled (`__disabled__` tag, dead code)
- ~17 missing entirely

The qa-tester didn't catch this because its job is correctness
("cascades fire from manual setup") not coverage ("does every
promise in the GDD have a wired implementation?").

This skill's output is the missing measurement. Fed back to the
orchestrator, it lets autonomous mode LOOP: build → audit → fix-gaps
→ audit → ... until coverage crosses a threshold (typically 80%) OR
the user explicitly accepts a lower delivery.

## Inputs and outputs

This skill runs as a forked skill (ADR 0082, phase 2). It runs in its
own subagent and does not see the chat history. The arguments and the
files below carry all the input. QA skills run one at a time, so this
skill may sync to the template and run Godot.

1. **Arguments.** The game slug. Example: `demo_x`. The design files
   are under `docs/games/<name>/`, and the build is under
   `godot/data/demo_<name>/`.
2. **Output.** Write `docs/games/<name>/coverage.md` (shape below).
3. **Return.** Reply in 200 words or fewer: the REQUIRED, IMPORTANT
   and NICE percentages, the output path, and the top 3 gaps for the
   caller. The caller reads the full result from the file.

## Inputs you accept

- `docs/games/<name>/GDD.md` — the source of truth for promises
- `docs/games/<name>/world-plan.md` — concrete entity catalog
- `docs/games/<name>/level-design.md` (if present) — spatial promises
- `docs/games/<name>/story-design.md` (if present) — narrative beats
- `docs/games/<name>/economy-design.md` (if present) — numeric promises
- The build under `godot/data/demo_<name>/` — what's actually wired

## Outputs you produce

A coverage audit at `docs/games/<name>/coverage.md`:

```markdown
# <Game name> — GDD coverage audit

_Date: YYYY-MM-DD_
_Auditor: yume-gdd-coverage-tracker_
_GDD: docs/games/<game-name>/GDD.md_
_Build: godot/data/demo_<name>/_

## Verdict

**Coverage: 32% (67 / 207 promises)**
**Status: revise** — below 80% threshold

## Summary by category

| Category | Implemented | Disabled | Missing | % |
|---|---|---|---|---|
| Player verbs | 4 | 1 | 4 | 44% |
| Customer archetypes | 5 | 0 | 0 | 100% |
| Items catalog | 3 | 0 | 19 | 14% |
| ... | | | | |

## Per-promise checklist

(See sections below — every named GDD entity gets a row.)

## Top 10 gaps to close

Ordered by impact + effort:
1. **Real haggle UX** — signature mechanic, GDD § 3.
   Engine pattern: thread customer_id via signal payload to screen,
   accept/counter/reject buttons emit signals back. ~50 LOC JSON.
2. **Morning supplier phase** — entirely missing, GDD § Phase Table.
   ...
```

## Promise extraction methodology

The GDD is a prose document. Extracting a checklist requires
reading systematically across these sections:

### From any GDD

- **Mechanics → entities**: every named entity type (player, NPCs,
  items, props, monsters) → must have an entity def
- **Mechanics → key states**: every named world_state field → must
  appear in world_clock state_init or world/state.json
- **Mechanics → key relations**: every named relation type → must
  appear in initial_relations or rule effects
- **Mechanics → player verbs**: every input action listed → must
  have ≥1 enabled rule subscribing
- **Dynamics → cascades**: every named cascade ("gold spiral",
  "reputation gate", "inventory pressure") → must have rule chain
  visible in world/rules/*.json feature modules (or legacy single-file
  world/rules.json for smaller games)
- **Aesthetic → audio cues**: every cue named in `## Audio cues` →
  must be in audio/cues.json
- **Aesthetic → signature beats**: every named scripted moment →
  must have a triggering rule + the entities it spawns
- **Pacing → phase table**: every phase in the daily/level cycle →
  must have a triggering rule, distinct verbs, distinct HUD
- **Replay → difficulty modes**: every mode → must have a state_set
  in difficulty_select screen + queries that read difficulty
- **Pause UX → pause menu**: every option promised → must be in
  screens.json
- **Save → manual + auto slots**: counts must match save_policy.json

### From genre-specific sections (merchant)

- **Adventurer-class table**: every row → entity def + spawn rule
- **Class-gear coverage**: every cell → item def + customer want
- **Daily cycle phase table**: every phase → distinct game mode
- **Haggle mechanic spec**: exchange flow → screen + signal chain
- **Debt schedule**: every installment day → rule with day_eq filter

### From world-plan.md

- **Cast section**: every `npc_xxx` id → entity def + spawn rule
- **Items catalog**: every `item_xxx` id → entity def + reachable
  source (supplier/dungeon/quest)
- **Plant catalog**: every `plant_xxx` → growth rule chain
- **Event calendar**: every entry → triggering rule

### From level-design.md

- **Map dimensions**: actual `data/<name>/scene.json` bounds match
- **Placement table**: every entity at expected position (within ±5%)

### From story-design.md

- **Beat list**: every beat ID → rule that fires it + Pre-req chain
- **Character arcs**: every arc stage → state field + transition rule

### From economy-design.md

- **Source/sink table**: every gold/resource source → at least one
  rule that adds it; every sink → at least one rule that subtracts

## Per-promise check definitions

For each extracted promise, perform a structured check:

### Entity def existence
```bash
grep -l "\"id\": \"<id>\"" godot/data/demo_<name>/entities/*.json
```
- ✓ if found in any file under `entities/`
- ✗ if not found anywhere

### Rule subscription
```bash
grep -rB 5 "\"action\": \"<verb>\"" godot/data/demo_<name>/world/rules/ \
  godot/data/demo_<name>/world/rules.json 2>/dev/null
# Verify enclosing rule does NOT have:  "tags_all": ["__disabled__"]
```
- ✓ if found AND enclosing rule has no `__disabled__` tag
- ⚠ if found but disabled (counts as "in code, not shipped")
- ✗ if no match

### State field existence
```bash
jq '.state' godot/data/demo_<name>/world/state.json | grep "<field>"
# OR check world_clock entity state_init
```
- ✓ if present in world/state.json or world_clock.state_init

### Screen existence
```bash
jq '.screens[] | .id' godot/data/demo_<name>/screens.json | grep "<id>"
```
- ✓ if found
- ✗ if no screens.json or id missing

### Phase distinctness (special — multi-step)
For each phase claimed in GDD:
1. Find rule that ENTERS the phase (state_set phase=X)
2. Find ≥1 rule with `phase_eq: "X"` query (means a verb gates on
   phase)
3. Verify phase has UNIQUE verb (not ≡ another phase)

- ✓ if all three pass
- ⚠ if entered but no gating queries
- ✗ if no rule enters phase OR phase variable unused

### Reachability (player-driven)
For verbs in HUD `controls_hint`:
1. Run scenario test: `actions: [{tick: 1, input: "<verb>"}]`
2. Assert visible state delta within 5 ticks

- ✓ if scenario passes
- ✗ if no state delta (verb is dead key)

### Signal-effect chain
For events / cascades:
1. Find emit_X rule
2. Find consume_X (signal trigger) rule
3. Both must be enabled

- ✓ both rules exist + enabled
- ⚠ emit exists but no consumer (signal goes nowhere)
- ✗ neither

## Methodology — step by step

When invoked:

1. **Read all input docs** (GDD, world-plan, level-design,
   story-design, economy-design as available).

2. **Build the promise list**. Walk each section and extract every
   named promise into a flat list:
   ```
   [type, id, source_doc, source_line, severity]
   ```
   - type ∈ {entity, verb, screen, phase, signal, event, beat,
     cascade, audio_cue, state_field, relation, item, npc}
   - severity ∈ {required, important, nice-to-have} based on whether
     the GDD calls it core (e.g. "signature mechanic") or aside

3. **Run checks per promise**. Use the check definitions above.
   Each promise gets a status: ✓ / ⚠ / ✗.

4. **Compute coverage**. Implementation rate = (✓) / total. Disabled
   doesn't count. Severity-weighted variant: required = 3x,
   important = 2x, nice = 1x — but report unweighted as the
   primary number.

5. **Categorize gaps**. Group ✗ + ⚠ items by category. Identify
   the top-10 by impact (severity × user-visible).

6. **Write `coverage.md`** with the verdict + summary table +
   per-promise checklist + top gaps.

7. **Return 6-line summary**: total promises / coverage % / verdict
   (accept ≥ 80% / revise < 80% / reject if pipeline broken) /
   top 3 categories with most gaps / top 1 gap to close first /
   ETA estimate (rough) for closing top 5 gaps.

## Verdict thresholds

**Principle**: a GDD is a CONTRACT. Anything written in it is a
promise. The tracker's job is to enforce that promises either land
in the build OR get cut from the GDD with explicit rationale. There
is no third option ("silently dropped" is the failure mode this
skill exists to prevent).

**Severity-weighted threshold (replaces the prior 80% global)**:

- **Required-severity ✓ rate: must be 100%.** No exceptions.
  Required = anything the GDD calls signature, core mechanic,
  win/lose path, named in the one-line pitch, or part of the
  primary aesthetic target. If a required promise can't be
  delivered this session, the orchestrator MUST surface it with a
  GDD-revision proposal (see below); it cannot be silently
  deferred.
- **Important-severity ✓ rate: ≥ 90%.** Important = secondary
  mechanics, named NPCs/items not pitch-essential, polish layers.
  Misses must be itemized (not aggregated as "8% gap").
- **Nice-to-have ✓ rate: ≥ 60%, but every gap must be NAMED.**
  Nice = audio variants, decorative entities, alternate visuals.
  No silent drops. Each missing nice-to-have has a one-line
  reason in the report.

### Verdict types

- **accept**: required = 100%, important ≥ 90%, every nice gap
  has a documented reason. Game ships.
- **revise**: any required ✗, OR important < 90%. Loop back to
  designers with the gap list as a checklist. Orchestrator runs
  another pass.
- **reject + propose**: a required-severity gap CANNOT be closed
  in this iteration cycle (engine block, design contradiction,
  scope-out-of-bounds). Skill emits a **GDD-revision proposal**
  alongside the coverage report. Surface to user.

### GDD-revision proposal (when required gaps can't be closed)

When the tracker detects a required ✗ that's been the same for ≥ 2
loop iterations, it stops looping and outputs a section in
`coverage.md`:

```markdown
## GDD-revision proposal — required gaps that cannot be closed

Two iterations have not closed these required-severity promises.
Either the implementation needs an engine extension, OR the GDD
should be amended.

### Gap: <promise name>

- **GDD ref**: docs/games/<name>/GDD.md § <section>, line <n>
- **Block**: <why it can't be implemented now>
- **Options for user**:
  1. Build the engine extension (estimated: ADR + N hours).
     Specifically, need primitive `<X>` to express `<Y>`.
  2. Cut from GDD: edit GDD.md § <section> to remove `<promise>`.
     Aesthetic impact: <what changes about the game's feel>.
  3. Substitute with a simpler design: `<concrete alternative>`.

User picks 1 / 2 / 3.
```

The orchestrator surfaces this to the user. It does NOT pick on
the user's behalf. Required-severity gaps require explicit
acknowledgment.

### Why not just demand 100% of everything

A literal 100% on the entire GDD is unrealistic for a single
autonomous run because:

1. The GDD is written before any code lands; some promises turn
   out to be impossible / contradictory once the engine constraints
   are felt.
2. Some nice-to-haves (8th audio cue, a specific decorative entity
   color) genuinely don't break the game if missed.
3. Engine gaps may require ADRs that are out-of-scope for THIS
   session.

But the skill MUST track 100% across iterations and surface drops
explicitly, not silently. Every drop is a user decision, not an
implicit "good enough" call by the build pipeline.

### Tier-honest reporting

If a build is shipped at less than 100% required (because user
explicitly accepted via the GDD-revision proposal flow), the
coverage report's verdict line MUST say:

> "accept (with explicit GDD revisions: <list>)"

Not "accept" alone. Future readers (and future sessions) need to
know what was promised vs delivered.

## How to be honest, not punitive

This skill gives an HONEST measurement, not a punishment. The
skill's verdict is read by:
1. The orchestrator (decides next pass)
2. The user (decides whether to expand GDD or descope)

Format the coverage report so it's actionable. Each ✗ row should
have an "Implementation hint" pointing to the file and skill that
needs to act. Each ⚠ row should explain WHY disabled and what
should re-enable.

Don't moralize. "GDD says X, build has Y. Gap: X-Y. Fix path:
content-designer adds X to entities/." Plain English, no editorializing.

## When invoked by orchestrator

Position in pipeline: AFTER yume-qa-tester. BEFORE final
accept/revise decision. Loops with content/rules/asset designers
until coverage threshold reached.

Concretely in /yume-design --autonomous mode:
1. Designers produce content
2. qa-tester runs scenario tests + visual capture
3. **gdd-coverage-tracker runs (this skill)**
4. If coverage ≥ 80% AND no required ✗ → accept, ship
5. If coverage 50-80% → revise: feed gap list back to
   content/rules/asset designers, run again
6. If coverage < 50% → reject, surface to user

The orchestrator should cap loop iterations (e.g. max 3) to avoid
infinite revise cycles. Diminishing returns kick in after pass 2-3
typically.

## What you DON'T do

- ❌ Modify entities/rules/screens (that's the designers' job).
- ❌ Edit the GDD (that's user/game-designer's job).
- ❌ Run scenario tests yourself (qa-tester does that, you read its
  results).
- ❌ Mark something ✓ without proof (grep result, scenario pass, etc.)
- ❌ Skip categories because they're tedious. The point is HONEST
  coverage. If you skip the items catalog because there's 22 items,
  you've defeated the purpose.

## Reference files

- `docs/games/<name>/GDD.md` — the contract
- `.claude/skills/yume-qa-tester/SKILL.md` — Input-coverage gate
  (this skill extends qa-tester's check from "input wired" to
  "GDD promise wired")
- `.claude/skills/yume-merchant-reviewer/SKILL.md` — genre reviewer
  has axes that overlap; use them as cross-reference (Axis 9
  phase fidelity, Axis 10 input + verb coverage)
- `godot/data/demo_<name>/` — the build under audit

## Status

Created 2026-05-07 in response to the empirical merchant build that
shipped at 32% GDD coverage with qa-tester verdict "complete." This
skill closes the loop: no more shipping at 32% by accident.