/reverse-document

name: reverse-document
description: "Writes missing design or architecture docs, or a game's brief, from code. Use when code or prototypes have no docs."
argument-hint: "<type> <path> (e.g., 'design src/gameplay/combat', 'architecture Assets/Scripts/Core' or 'brief prototypes/my-game')"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Bash(bash "*/.claude/skills/reverse-document/../../hooks/yaml-helper.sh" resolve_config *), Bash(bash .claude/scripts/game-read.sh *)
model: sonnet
# Read-only diagnostic skill — no specialist agent delegation needed

Reverse Documentation

This skill analyzes existing implementation (code, prototypes, systems) and generates appropriate design or architecture documentation. Use this when:

• You built a feature without writing a design document first
• You inherited a codebase without documentation
• You prototyped a mechanic and need to formalize it
• You need to document "why" behind existing code

---

Workflow

Phase 1: Parse Arguments

**Format**: `/reverse-document <type> <path>`

**Type options**:

• `design` → Generate a game design document (GDD section)
• `architecture` → Generate an Architecture Decision Record (ADR)
• `concept` → Generate a concept document from prototype
• `brief` → The one-page brief of a browser game someone already made (an `.html` file or a

folder with `index.html`), its Features marked built. **Read `references/from-a-game.md` now and follow it**: it takes the place of Phases 2 to 7 for a game. For any other type, do not load it.

**Path**: Directory or file to analyze, under the code root — `src/` Godot, `Assets/` Unity, `Source/<Module>/` Unreal (`.claude/docs/code-root-resolution.md`)

• `src/gameplay/combat/` → All combat-related code (Godot)
• `Assets/Scripts/Core/EventSystem.cs` → Specific file (Unity)
• `Source/MyGame/Private/AI/` → A module folder (Unreal)
• `prototypes/stealth-mech/` → Prototype directory

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

**Automation mode**: Resolve `modes.automation` (`project.local.yaml` → `project.yaml` → default `collaborative`). Every question 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`.

**Resolve the workflow tier** for the target system: map `<path>` to a system name, then use the `system_overrides` row for that system if the block above lists one, else the project `workflow` value. It sets how much document is generated — see Phase 5. Semantics of each tier are in `.claude/docs/workflow-modes.md`.

> **Resolve the tier — do not assume it.** `workflow-modes.md` defines what each > tier *means*, but it cannot say what *this project* is set to; take that from > the block above. The consequence is large here — at `full` this skill > writes an 8-section GDD and at `minimal` a one-page brief, so a wrong tier > produces the wrong artifact entirely.

**Examples**:

/reverse-document design src/gameplay/magic-system
/reverse-document architecture Source/MyGame/Private/EntityComponent
/reverse-document concept prototypes/vehicle-combat

Phase 2: Analyze Implementation

**Read and understand the code/prototype**:

**For design documents (GDD):**

• Identify mechanics, rules, formulas
• Extract gameplay values (damage, cooldowns, ranges)
• Find state machines, ability systems, progression
• Detect edge cases handled in code
• Map dependencies (what systems interact?)

**For architecture docs (ADR):**

• Identify patterns (ECS, singleton, observer, etc.)
• Understand technical decisions (threading, serialization, etc.)
• Map dependencies and coupling
• Assess performance characteristics
• Find constraints and trade-offs

**For concept docs (prototype analysis):**

• Identify core mechanic
• Extract emergent gameplay patterns
• Note what worked vs what didn't
• Find technical feasibility insights
• Document player fantasy / feel

Phase 3: Ask Clarifying Questions

Ask about intent; the person can read the code already:

**Design questions**:

• "I see a [resource] system that depletes during [activity]. Was this for:
• Pacing (prevent spam)?
• Resource management (strategic depth)?
• Or something else?"
• "The [mechanic] seems central. Is this a core pillar, or supporting feature?"
• "[Value] scales exponentially with [factor]. Intentional design, or needs rebalancing?"

**Architecture questions**:

• "You're using a service locator pattern. Was this chosen for:
• Testability (mock dependencies)?
• Decoupling (reduce hard references)?
• Or inherited from existing code?"
• "I see manual memory management instead of smart pointers. Performance requirement, or legacy?"

**Concept questions**:

• "The prototype emphasizes stealth over combat. Is that the intended pillar?"
• "Players seem to exploit the grappling hook for speed. Feature or bug?"

Phase 3b: Sufficiency Check — is there enough here to document?

**Run this before Phase 4, and stop here if it fails.** This skill infers a design from an implementation, so when the implementation is thin there is nothing to infer *from* — and the template below will happily accept invented content, because every section of it is mandatory.

Count what Phase 2 actually found:

| Signal | What counts | |---|---| | Mechanics | A named behaviour with observable rules — not a stub, not an empty class | | Formulas | An expression computing a gameplay value from inputs | | Values | A tuning constant with a use site |

**If all three counts are zero, or the target path holds fewer than ~20 lines of non-boilerplate code, stop and say so:**

> "`[path]` does not contain enough implementation to reverse-document. > Found: [N] mechanics, [N] formulas, [N] tuning values. > Reverse-documentation i