/content-audit

name: content-audit
description: "Audit GDD content counts against what's implemented — planned vs built."
argument-hint: "[system-name | --summary | (no arg = full audit)]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Bash(bash "*/.claude/skills/content-audit/../../hooks/yaml-helper.sh" resolve_config *)
model: sonnet

!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys workflow,automation`

**Automation mode**: Resolve `modes.automation` (`project.local.yaml` → `project.yaml` → default `collaborative`). Every `AskUserQuestion` call and every file write follows `.claude/docs/automation-modes.md` (collaborative asks always · guided major-only · autonomous logs and proceeds; `automation_always_ask` categories always prompt).

Resolved above — use as-is. No block → defaults in `.claude/docs/config-resolution.md`.

Content Audit

> Resolve `modes.workflow` before auditing: this skill's tier-dependent behaviour > ("audit only specs in the required sections") follows the resolved tier, never > an assumed one. When a required input such as `design/gdd/systems-index.md` is > absent, report > **`NOT ASSESSED — NO DATA`** rather than computing a gap percentage (which > divides by zero when nothing is specified).

When this skill is invoked:

Parse the argument:

• No argument → full audit across all systems
• `[system-name]` → audit that single system only
• `--summary` → summary table only, no file write

---

**`workflow`** (see `.claude/docs/workflow-modes.md`):

• `full` — full content-count audit against all GDD specs.
• `standard` — audit only specs in the required sections; list any count found

outside them as not audited at this tier.

• `minimal` — cannot run (no systems index exists).

Insufficient input — check this before producing any report

**If the inputs this skill needs do not exist, the answer is "could not run" — not a filled-in report.** Check first, and stop if the check fails.

1. List the inputs this skill reads (data files, prior reports, profiler output, test results, registries, source code). 2. For each, record `FOUND` or `ABSENT` — not "assumed present". 3. If any input required for a section is ABSENT, that section is **`NOT ASSESSED — NO DATA`**. Do not estimate it, do not infer it from an adjacent artifact, and do not leave a mandated cell to be filled by whoever reads the template next. 4. If **every** required input is ABSENT, stop and report **`NOT ASSESSED — NO DATA`** as the whole verdict, naming what was missing and which skill produces it (`/map-systems` for `design/gdd/systems-index.md`, `/design-system` for the GDDs).

**A verdict of `NOT ASSESSED` is a success.** It is the correct, useful answer to "what does the data say?" when there is no data. The failure mode this prevents is specific: a report whose verdict enum has no "could not run" state produces **false clean passes** — an asset audit returning COMPLIANT on a project with no assets and no standards, or a performance profile reporting ">99% headroom against a 16.67ms budget" with zero profiler data and no budget ever set.

**Absence of evidence is never evidence of absence.** A scan that finds no matches because there are no files to scan has not verified anything. Say which of the two happened — a reader cannot tell from a green result.

---

Phase 1 — Context Gathering

1. **Read `design/gdd/systems-index.md`** for the full list of systems, their categories, and MVP/priority tier. Read it by section: find the headings you need with the Grep tool (pattern `^#`, content mode) and Read those ranges with offset and limit.

2. **Registry-first count**: If `design/registry/entities.yaml` exists, read it first. Its `entities` and `items` sections are the cross-GDD named content the audit is counting, already distilled with a `source:` GDD per entry:

   Grep pattern="^  - name:" path="design/registry/entities.yaml" output_mode="content" -A 2

`- name:` appears in all four registry sections; keep only the names whose `-A 2` context shows they sit under `entities:` or `items:` (the named content this audit counts — not `formulas:`/`constants:`). Use those as the **planned** named-content set without full-reading the GDDs that own them. **If `design/registry/entities.yaml` does not exist or has no entries** (it ships as an empty stub until `/design-system` populates it), skip this step and rely on the GDD scan below — behaviour is unchanged, only more expensive.

3. **L0 pre-scan**: Before full-reading any GDDs, run **two** greps — they answer different questions and must not share a pattern:

a. Which GDDs carry a Summary (the denominator / fail-open check):

   Grep pattern="^## Summary" glob="design/gdd/*.md" output_mode="files_with_matches"

b. Which GDDs actually declare content counts (the narrowing step):

   Grep pattern="[0-9]+[[:space:]]+(enemies|enemy types|levels|areas|maps|stages|items|weapons|equipment|abilities|skills|spells|cutscenes|conversations|dialogue scenes|bosses|quests)|(enemy|item|weapon|ability|level) types:" glob="design/gdd/*.md" output_mode="files_with_matches"

> **Keep the two scans separate.** `## Summary` matches every compliant GDD, > so a union with it narrows nothing, and a literal placeholder such as > `N enemies` matches no real GDD. Pattern (b) matches digits followed by the > content nouns step 5 actually extracts.

**Fail open on a missing Summary.** Establish the denominator: glob `design/gdd/*.md` and count **N**. **Scan (a)** matching fewer than N means those GDDs predate `## Summary` — never treat an absent Summary as a system out of scope; a zero-match (a) means "no GDD carries a Summary yet", not "no auditable content". Full-read the unmatched in-scope GDDs.

For a single-system audit: skip this step and go straight to full-read. For a full audit: full-read the GDDs that