Claude-Code-Game-Studios/CCGS Skill Testing Framework/skills/utility/reverse-document.md

# 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`.
`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.

---

## Test Cases

### Case 1: Well-Structured Source at `full` — 8-section GDD produced

**Fixture:**
- `project.yaml` resolves `workflow: full`; no `system_overrides` row for health
- `src/gameplay/health_system.gd` exists (~80 lines) with:
  - `@export var max_health: int = 100`
  - `func take_damage(amount: int)` containing
    `health = clamp(health - amount, 0, max_health)`
  - `signal health_changed(new_value: int)`
  - Docstrings on all public methods
- The user answers every `UNCLEAR INTENT AREAS` question and approves the write

**Input:** `/reverse-document design src/gameplay/health_system.gd`

**Expected behavior:**
1. Skill reads the source and passes the Phase 3b sufficiency check
2. Skill presents findings (MECHANICS IMPLEMENTED, FORMULAS DISCOVERED,
   UNCLEAR INTENT AREAS) and waits for answers before drafting
3. Skill drafts an 8-section GDD (Overview, Player Fantasy, Detailed Rules,
   Formulas, Edge Cases, Dependencies, Tuning Knobs, Acceptance Criteria)
4. The Formulas section records the clamp expression; Tuning Knobs lists
   `max_health = 100`
5. The provenance banner ("Reverse-documented from implementation … from
   `src/gameplay/health_system.gd`") sits directly under the title
6. Skill asks "May I write this to `design/gdd/health-system.md`?"
7. 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 = 100` appears 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.yaml` resolves `workflow: full`
- `src/gameplay/enemy_ai.gd` exists (~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:**
1. Sufficiency check passes (mechanics and tuning values found)
2. Findings list the state machine under MECHANICS IMPLEMENTED, the two
   constants as values, and `FORMULAS DISCOVERED: none found in the source`
3. UNCLEAR INTENT AREAS asks what the constants represent (e.g. whether 150 is
   an aggro range and in what units)
4. 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
5. No formula is invented to fill the Formulas section
6. Skill asks "May I write this to `design/gdd/enemy-ai.md`?"; verdict COMPLETE
   on approval

**Assertions:**
- [ ] `FORMULAS DISCOVERED` reads `none 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.yaml` resolves `workflow: minimal`
- `src/core/combat/` holds `combat_system.gd` and `damage_resolver.gd`;
  `combat_system.gd` calls `damage_resolver.gd` through an injected reference
- The user answers the architecture questions and approves the write

**Input:** `/reverse-document architecture src/core/combat/`

**Expected behavior:**
1. Skill reads every file under the directory path
2. Phase 2 architecture analysis maps the dependency and coupling between the
   two files (combat_system → damage_resolver)
3. Phase 3 asks architecture-intent questions (e.g. why the resolver is
   injected) rather than only describing the code
4. Draft uses the `architecture-doc-from-code.md` template — the `minimal` tier
   does NOT turn it into a one-page brief
5. 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/`, not `design/gdd/` or a `-brief.md`
- [ ] The `minimal` tier does not change the architecture output
- [ ] Verdict is COMPLETE

---

### Case 4: Thin Source — Sufficiency check stops the run

**Fixture:**
- `src/gameplay/inventory_system.gd` exists with only
  `class_name InventorySystem`, `extends Node` and 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:**
1. Skill reads the file; Phase 3b counts 0 mechanics, 0 formulas, 0 values
2. Skill stops with: "`src/gameplay/inventory_system.gd` does not contain enough
   implementation to reverse-document. Found: 0 mechanics, 0 formulas, 0 tuning
   values. …"
3. Skill points to `/design-system [name]` as the skill that captures a design
   that exists only in the user's head
4. 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-system` is 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:**
1. Skill analyzes, presents findings, and drafts the document
2. No director agents are spawned; no gate IDs appear in output
3. 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.yaml` sets no `modes.rigor` and no `modes.workflow`, so the resolved
  tier is `minimal` — the default; no `system_overrides`
- Same source as Case 1 (`src/gameplay/health_system.gd`)
- The user answers every `UNCLEAR INTENT AREAS` question and approves the write

**Input:** `/reverse-document design src/gameplay/health_system.gd`

**Expected behavior:**
1. The tier resolves to `minimal` from the config block, not assumed
2. Findings are presented and answered before any draft
3. The draft is a one-page game brief in the `.claude/docs/templates/game-brief.md`
   format — not a GDD — for this one system
4. The provenance banner sits directly under the title
5. Skill asks "May I write this to `design/health-system-brief.md`?" — not
   `design/gdd/` and not `design/game-brief.md`, which is the whole-game brief
6. 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

---

## 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`
- [ ] `design` output matches the resolved tier (8 sections at `full`, 5 at `standard`, brief at `minimal`)
- [ ] 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 `standard` tier (5-section GDD without Player Fantasy and Tuning Knobs)
  follows Case 1's flow with a different section set; not separately
  fixture-tested. The `minimal` brief is Case 6.
- The `concept` type (prototype → `prototypes/[name]/CONCEPT.md` or
  `design/concepts/[name].md`) is not separately tested.
- `guided` and `autonomous` automation modes change the write prompt per
  `automation-modes.md`; only `collaborative` is tested here.