game-reverse-document

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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 scenes/levels: [N]
  - Number of asset files: [N]
  - Estimated project complexity: [small / medium / large]

Step 4: Check for existing documentation
  - README present: [Y/N]
  - Design document present: [Y/N]
  - Inline comments density: [sparse / moderate / thorough]
  - Architecture docs present: [Y/N]
-------------------------------------------------
```

---

🎯 **PHASE 2: System Detection**

*Goal: Identify distinct game systems from code patterns.*

Game systems leave recognizable fingerprints in code regardless of engine or language. This
phase identifies which systems exist by scanning for characteristic patterns.

```
SYSTEM DETECTION HEURISTICS
-------------------------------------------------
MOVEMENT SYSTEM:
  Signals: velocity variables, position updates per frame, input axis
  reading, acceleration/deceleration curves, ground detection, gravity
  application, jump state machines, character controller references
  Common files: Player.*, CharacterController.*, Movement.*, Locomotion.*

COMBAT SYSTEM:
  Signals: damage calculation functions, health/HP variables, hit detection,
  attack state machines, weapon data structures, damage types/resistances,
  invincibility frames, knockback vectors
  Common files: Combat.*, Weapon.*, DamageSystem.*, Health.*, Attack.*

INVENTORY SYSTEM:
  Signals: item data structures, add/remove item functions, capacity limits,
  item stacking logic, equipment slots, item categories/types
  Common files: Inventory.*, Item.*, Equipment.*, ItemDatabase.*

From AlterLab-IEU/AlterLab_GameForge, MIT.

More from AlterLab-IEU/AlterLab_GameForge