content-audit
Audit GDD content counts against what's implemented — planned vs built.
HYClub · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add HYClub/deepseek-harness-game-studios --skill 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.
This skill declares tier-dependent behaviour ("audit only specs in the required sections"), which is unreachable unless the tier is actually resolved — without it the skill applies whatever tier it assumed. Resolve
modes.workflowbefore auditing, and when a required input such asdesign/gdd/systems-index.mdis absent, reportNOT ASSESSED — NO DATArather 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.
- List the inputs this skill reads (data files, prior reports, profiler output, test results, registries, source code).
- For each, record
FOUNDorABSENT— not "assumed present". - 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. - If every required input is ABSENT, stop and report
NOT ASSESSED — NO DATAas the whole verdict, naming what was missing and which skill produces it (/map-systemsfordesign/gdd/systems-index.md,/design-systemfor 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 and has been observed in practice: report templates whose verdict
enum had no "could not run" state produced false clean passes — an asset audit
returning COMPLIANT on a project with no assets and no standards, and 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
-
Read
design/gdd/systems-index.mdfor the full list of systems, their categories, and MVP/priority tier. -
Registry-first count: If
design/registry/entities.yamlexists, read it first. Itsentitiesanditemssections are the cross-GDD named content the audit is counting, already distilled with asource: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 2context shows they sit underentities:oritems:(the named content this audit counts — notformulas:/constants:). Use those as the planned named-content set without full-reading the GDDs that own them. Ifdesign/registry/entities.yamldoes not exist or has no entries (it ships as an empty stub until/design-systempopulates it), skip this step and rely on the GDD scan below — behaviour is unchanged, only more expensive. -
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.
## Summarymatches every compliant GDD, so a union with it narrows nothing, and a literal placeholder such asN enemiesmatches 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/*.mdand 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 scan (b) matched **and are not a