Turn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.
Skill Test Spec: /reverse-document
Skill Summary
/reverse-document <type> <path> works backwards from existing implementation to
a document. type is design (a GDD, written to design/gdd/[system-name].md),
architecture (an ADR, written to docs/architecture/[decision-name].md) or
concept (a concept doc from a prototype). It reads the code, runs a
sufficiency check (stopping when there is too little implementation to infer
from), presents its findings with the questions code cannot answer, drafts the
document, and asks "May I write this to [output path]?".
The design output scales with the resolved workflow tier: an 8-section GDD at
full, a 5-section GDD at standard, a one-page brief at minimal (the whole-game design/game-brief.md when the path
is the code root, design/[system-name]-brief.md for one system).
architecture and concept outputs are tier-independent. Intent the user did
not confirm is carried into the document marked INTENT UNKNOWN — inferred from implementation, not confirmed, and every document carries a
"Reverse-documented from implementation" provenance banner. No director gates
apply. Verdicts: COMPLETE (document written after approval) or BLOCKED (user
declined the write).
Static Assertions (Structural)
Checked against the SKILL.md by /skill-test spec — no fixture needed.
- Has required frontmatter fields:
name,description,argument-hint,user-invocable,allowed-tools - Has ≥2 phase headings
- Contains verdict keywords: COMPLETE, BLOCKED
- Contains "May I write" collaborative protocol language before writing the doc
- Has a next-step handoff (Phase 8 follow-up list, e.g.
/balance-check)
Director Gate Checks
None. /reverse-document is a documentation utility. No director gates apply.
Fixture Defaults
Every case's project.yaml sets modes.rigor: minimal and
modes.automation: collaborative, with no project.local.yaml, unless its own
Fixture says otherwise. Rules: studio-tests/CLAUDE.md §
Fixture defaults.
Test Cases
Case 1: Well-Structured Source at full — 8-section GDD produced
Fixture:
project.yamlresolvesworkflow: full; nosystem_overridesrow for healthsrc/gameplay/health_system.gdexists (~80 lines) with:@export var max_health: int = 100func take_damage(amount: int)containinghealth = clamp(health - amount, 0, max_health)signal health_changed(new_value: int)- Docstrings on all public methods
- The user answers every
UNCLEAR INTENT AREASquestion and approves the write
Input: /reverse-document design src/gameplay/health_system.gd
Expected behavior:
- Skill reads the source and passes the Phase 3b sufficiency check
- Skill presents findings (MECHANICS IMPLEMENTED, FORMULAS DISCOVERED, UNCLEAR INTENT AREAS) and waits for answers before drafting
- Skill drafts an 8-section GDD (Overview, Player Fantasy, Detailed Rules, Formulas, Edge Cases, Dependencies, Tuning Knobs, Acceptance Criteria)
- The Formulas section records the clamp expression; Tuning Knobs lists
max_health = 100 - The provenance banner ("Reverse-documented from implementation … from
src/gameplay/health_system.gd") sits directly under the title - Skill asks "May I write this to
design/gdd/health-system.md?" - File written on approval; verdict is COMPLETE
Assertions:
- Findings are presented and answered before any draft is shown
- All 8 GDD sections are present (tier resolved as
full) - The clamp expression appears in Formulas;
max_health = 100appears as a Tuning Knob - The provenance banner appears directly under the title
- "May I write" names the path under
design/gdd/ - Verdict is COMPLETE
Case 2: Unanswered Intent — INTENT UNKNOWN carried into the draft
Fixture:
project.yamlresolvesworkflow: fullsrc/gameplay/enemy_ai.gdexists (~120 lines) with:- A patrol/chase/attack state machine
- Inline constants with use sites:
if distance < 150:,speed = 3.5 - No arithmetic expression that computes a gameplay value from inputs
- No comments or docstrings
- The user replies "just draft it" without answering the intent questions, then approves the write
Input: /reverse-document design src/gameplay/enemy_ai.gd
Expected behavior:
- Sufficiency check passes (mechanics and tuning values found)
- Findings list the state machine under MECHANICS IMPLEMENTED, the two
constants as values, and
FORMULAS DISCOVERED: none found in the source - UNCLEAR INTENT AREAS asks what the constants represent (e.g. whether 150 is an aggro range and in what units)
- Because the questions go unanswered, the draft carries each one verbatim as
an open question marked
INTENT UNKNOWN — inferred from implementation, not confirmed— it does not present an inferred intent as settled - No formula is invented to fill the Formulas section
- Skill asks "May I write this to
design/gdd/enemy-ai.md?"; verdict COMPLETE on approval
Assertions:
-
FORMULAS DISCOVEREDreadsnone found in the source(heading kept, not omitted) - Each unanswered question appears in the document marked
INTENT UNKNOWN — inferred from implementation, not confirmed - No formula or design intent absent from the code appears in the draft
- "May I write" is asked before the file is written
- Verdict is COMPLETE
Case 3: Architecture Type on Interdependent Files — tier-independent ADR
Fixture:
project.yamlresolvesworkflow: minimalsrc/core/combat/holdscombat_system.gdanddamage_resolver.gd;combat_system.gdcallsdamage_resolver.gdthrough an injected reference- The user answers the architecture questions and approves the write
Input: /reverse-document architecture src/core/combat/
Expected behavior:
- Skill reads every file under the directory path
- Phase 2 architecture analysis maps the dependency and coupling between the two files (combat_system → damage_resolver)
- Phase 3 asks architecture-intent questions (e.g. why the resolver is injected) rather than only describing the code
- Draft uses the
architecture-doc-from-code.mdtemplate — theminimaltier does NOT turn it into a one-page brief - Skill asks "May I write this to
docs/architecture/[decision-name].md?"; verdict COMPLETE on approval
Assertions:
- Both files are analyzed, and the combat_system → damage_resolver dependency is documented
- Output is an ADR at
docs/architecture/, notdesign/gdd/or a-brief.md - The
minimaltier does not change the architecture output - Verdict is COMPLETE
Case 4: Thin Source — Sufficiency check stops the run
Fixture:
src/gameplay/inventory_system.gdexists with onlyclass_name InventorySystem,extends Nodeand an empty_ready()— no mechanics, no formulas, no tuning values (under 20 non-boilerplate lines)
Input: /reverse-document design src/gameplay/inventory_system.gd
Expected behavior:
- Skill reads the file; Phase 3b counts 0 mechanics, 0 formulas, 0 values
- Skill stops with: "
src/gameplay/inventory_system.gddoes not contain enough implementation to reverse-document. Found: 0 mechanics, 0 formulas, 0 tuning values. …" - Skill points to
/design-system [name]as the skill that captures a design that exists only in the user's head - No findings are presented, no draft is produced, no file is written
Assertions:
- The stop message names the path and the three counts (all 0)
-
/design-systemis suggested — not a fabricated skeleton - No write tool is called
- No verdict is issued (the run stops before Phase 4)
Case 5: Director Gate Check — No gate; declined write is BLOCKED
Fixture:
- Same source as Case 1; the user declines at the "May I write" prompt
Input: /reverse-document design src/gameplay/health_system.gd
Expected behavior:
- Skill analyzes, presents findings, and drafts the document
- No director agents are spawned; no gate IDs appear in output
- User declines the write; no file is created
Assertions:
- No director gate is invoked
- No gate skip messages appear
- Verdict is BLOCKED (user declined write) — no gate verdict involved
Case 6: Default Tier — a single system becomes a one-page brief
Fixture:
project.yamlsets nomodes.rigorand nomodes.workflow, so the resolved tier isminimal— the default; nosystem_overrides- Same source as Case 1 (
src/gameplay/health_system.gd) - The user answers every
UNCLEAR INTENT AREASquestion and approves the write
Input: /reverse-document design src/gameplay/health_system.gd
Expected behavior:
- The tier resolves to
minimalfrom the config block, not assumed - Findings are presented and answered before any draft
- The draft is a one-page game brief in the
.claude/docs/templates/game-brief.mdformat — not a GDD — for this one system - The provenance banner sits directly under the title
- Skill asks "May I write this to
design/health-system-brief.md?" — notdesign/gdd/and notdesign/game-brief.md, which is the whole-game brief - File written on approval; verdict COMPLETE
Assertions:
- The output is a brief in the game-brief format, not an 8- or 5-section GDD
- The path is
design/[system-name]-brief.md - The provenance banner appears under the title
- Verdict is COMPLETE
Case 7: Minimal Tier, Path Is the Code Root — the whole-game brief
Fixture:
project.yaml:engine.name: Godot(code rootsrc/);modes.rigor: minimal(workflowminimal); nosystem_overridessrc/holds a small finished game:src/gameplay/health_system.gd(as in Case 1),src/gameplay/enemy_ai.gd(as in Case 2) andsrc/main.gdthat starts the game loop — 14 source files in all- No
design/game-brief.mdexists - The user answers every
UNCLEAR INTENT AREASquestion and approves the write
Input: /reverse-document design src/
Expected behavior:
- The tier resolves to
minimalfrom the config block; the path is the code root itself, so the target is the whole game, not one system - Findings are presented and answered before any draft
- The draft is a one-page game brief in the
.claude/docs/templates/game-brief.mdformat covering the whole game (pitch, core loop, what is built), not a GDD and not a brief for one system - The provenance banner sits directly under the title
- Skill asks "May I write this to
design/game-brief.md?" — notdesign/gdd/, and not adesign/[system-name]-brief.mdpath - File written on approval; verdict COMPLETE
Assertions:
- The output is a one-page brief in the game-brief format covering the whole game
- The path is
design/game-brief.md, notdesign/[system-name]-brief.mdand not underdesign/gdd/ - The provenance banner appears under the title, and any intent the user did not confirm is marked
INTENT UNKNOWN — inferred from implementation, not confirmed - "May I write" names
design/game-brief.mdand is asked before the file is written - Verdict is COMPLETE
Case 7b — a path inside the code root: the same fixture with /reverse-document design src/gameplay/health_system.gd.
Assertions (7b):
- The brief is written to
design/health-system-brief.md(Case 6), never todesign/game-brief.md
Protocol Compliance
- Reads the source before generating any content
- Stops at the Phase 3b sufficiency check when mechanics, formulas and values all count zero
- Waits for answers to the intent questions; unanswered ones are carried as
INTENT UNKNOWN -
designoutput matches the resolved tier (8 sections atfull, 5 atstandard, brief atminimal—design/game-brief.mdwhen the path is the code root,design/[system-name]-brief.mdfor one system) - Emits the provenance banner under the title of every document it writes
- Asks "May I write" before creating any output file
- Verdict is COMPLETE (written) or BLOCKED (write declined)
Coverage Notes
- The
standardtier (5-section GDD without Player Fantasy and Tuning Knobs) follows Case 1's flow with a different section set; not separately fixture-tested. Theminimalbrief is Case 6 for one system and Case 7 for the whole game. - The
concepttype (prototype →prototypes/[name]/CONCEPT.mdordesign/concepts/[name].md) is not separately tested. guidedandautonomousautomation modes change the write prompt perautomation-modes.md; onlycollaborativeis tested here.