/game-reverse-document

name: "game-reverse-document"
description: >
  Generate documentation from existing code or prototypes. Triggers on: "document this",
  "reverse document", "generate docs from code", "onboard to codebase", "document existing
  system". Do NOT invoke for writing new design docs from scratch (use game-brainstorm or
  game-design-review). Part of the AlterLab GameForge collection.
argument-hint: "[path to code or 'project' for full scan]"
effort: medium
context: fork
allowed-tools: Read, Glob, Grep, Write, AskUserQuestion
version: 1.3.0

AlterLab GameForge -- Reverse Documentation Workflow

Most game projects start with passion, not paperwork. A developer prototypes, iterates, and builds. Weeks later, the codebase works but nobody -- including the original author -- can explain its architecture without reading every file. There is no design document because the design emerged from code. There is no architecture decision record because decisions were made in the moment and never written down. This is the normal state of indie development, and pretending otherwise is dishonest.

This workflow reverses the traditional documentation flow. Instead of document-then-build, it reads existing code and produces the documentation that should have existed from the start. The output is not auto-generated API docs -- it is human-readable design documentation that captures intent, architecture, and game systems in the language of game development, not the language of code.

Reverse documentation serves three critical needs: onboarding (a new team member understands the project in hours, not weeks of code archaeology), preservation (the original developer's decisions are captured before they forget why), and diagnosis (inconsistencies between systems become visible when documented side by side).

Purpose & Triggers

Use this workflow when:

• A prototype works but has zero documentation
• A new team member needs to understand an existing codebase
• The original developer is leaving and knowledge must be transferred
• The project has grown complex enough that the author loses track of systems
• Someone says "document this" or "what does this code do?"
• A game jam prototype is being promoted to a full project and needs formal docs
• An existing project needs a design document for publishers, investors, or team alignment

Problems this solves:

• Working code that nobody can explain or safely modify
• Onboarding that takes weeks of code-reading instead of hours of doc-reading
• Architectural decisions that are invisible -- embedded in code but never recorded
• Game mechanics that exist in code but are not described in any design document
• Systems that contradict each other because nobody mapped their interactions
• Orphaned code that does nothing but nobody is confident enough to delete

Critical Rules

1. **Read before writing.** Do not generate documentation from assumptions. Scan the actual codebase first. Every claim in the output must trace back to a specific file or code pattern. Include file paths and line references.

2. **Intent over implementation.** Capture WHY the code does something, not just WHAT it does. A function that applies gravity is not "applies downward force" -- it is "enforces the movement constraint that prevents infinite jumping." Celeste's codebase is full of intent-documenting comments like "coyote time: player can still jump for 6 frames after leaving a ledge." That level of intent documentation is the target.

3. **Flag uncertainty.** When the code's intent is ambiguous, say so. Mark sections with `[UNVERIFIED]` and ask the developer to clarify. Guessing intent and documenting the guess as fact is worse than leaving a gap.

4. **Systems, not files.** Organize documentation around game systems (movement, combat, inventory, UI), not around file structure. A movement system might span 5 files across 3 directories. The documentation describes the system, then lists the files. Dead Cells' internal documentation organized everything by game system -- combat, biomes, progression, enemies -- because that is how designers think about the game, not how the file tree is structured.

5. **Detect, do not ignore, inconsistencies.** If the movement code assumes tile-based movement but the collision code assumes continuous movement, that is a documentation finding, not something to paper over. Flag it. Factorio's codebase is a model of internal consistency -- every system agrees on what a "tick" means, what a "belt" can carry, and how entities interact. When your documentation reveals that two systems disagree on fundamentals, you have found the bug before it ships.

6. **Three modes, one pipeline.** The code analysis pipeline is shared across all three modes. The output format changes, not the analysis depth.

Workflow

---

🧠 **PHASE 1: Project Scan**

*Goal: Understand the project structure, engine, and organization before reading code.*

PROJECT SCAN PROTOCOL
-------------------------------------------------
Step 1: Detect engine and framework
  Scan for:
  - project.godot, *.gd, *.tscn         --> Godot
  - *.unity, *.cs, ProjectSettings/      --> Unity
  - *.uproject, *.cpp/*.h with UE macros --> Unreal Engine
  - package.json with game libs          --> Web/JS game framework
  - Cargo.toml with game crates          --> Rust game framework
  - None of the above                    --> Custom engine or unknown

Step 2: Map directory structure
  Produce a tree of the project with annotations:
  /project-root/
    /src/ or /scripts/    -- Game logic
    /assets/ or /art/     -- Visual and audio assets
    /scenes/ or /levels/  -- Level/scene data
    /ui/                  -- User interface
    /data/ or /config/    -- Game data, settings
    /tests/               -- Test files (if any)
    /docs/                -- Existing documentation (if any)

Step 3: Measure project scale
  - Total source files: [N]
  - Total lines of code: [approximate]
  - Number of sc