/game-reverse-document

name: game-reverse-document
description: >
  Generates docs from an existing game codebase as a forked report writer: reverse-engineered GDD,
  architecture overview with ADR drafts, concept document, or a one-page brief for new teammates and
  coding agents (Godot, Unity, Unreal, web). Use for "document this codebase", "generate docs from
  code", "onboard me to this codebase". Not for new designs (use game-gdd-author).
argument-hint: "[design|architecture|concept|brief] [path, default project root]"
effort: high
context: fork
allowed-tools: Read, Glob, Grep, Write, Bash(git log *), Bash(git diff *), Bash(git show *), Bash(git status *)

AlterLab GameForge -- Reverse Documentation

Most games start with passion, not paperwork. A prototype works, then grows, and weeks later nobody, including its author, can explain its architecture without reading every file. In 2026 add a new twist: much of that code was written by coding agents across dozens of sessions, each of which knew only what its prompt told it. The design lives in the code and in commit messages, nowhere else.

This workflow reads the code and writes the documents that should have existed: a design document in the language of game design, an architecture overview in the language of systems, a concept document that captures what the prototype is really about, or a one-page brief that lets a new teammate (human or agent) work safely on day one. It is not an API-doc generator.

Reverse documentation serves three needs: **onboarding** (hours of reading instead of weeks of archaeology), **preservation** (decisions captured before anyone forgets why), and **diagnosis** (systems that disagree become visible when documented side by side).

How this skill runs

This skill runs as a **forked subagent**: no conversation history, no questions to the user, read access to the repository plus `git log/diff/show/status`, and permission to write new documentation files. Therefore:

• **Never ask.** Choose the mode and scope with the rules below and list every assumption at the top

of the document under "Assumptions and limits".

• **Never edit code or existing documents.** Write new files only. If the target file exists, write

a dated sibling (`...-2026-11-05.md`) and note it.

• **Finish with a summary message:** mode, files written, systems documented, the three most

important inconsistencies or gaps, and the count of UNVERIFIED items the team should confirm.

Resolving `$ARGUMENTS`

| First word | Mode | Output file | |---|---|---| | `design` | Reverse-engineered GDD | `design/gdd-reverse-YYYY-MM-DD.md` | | `architecture` | Architecture overview plus ADR drafts | `docs/architecture/overview-YYYY-MM-DD.md`, `docs/architecture/adr-draft-NNN-<slug>.md` | | `concept` | Concept document from a prototype | `design/concept-reverse-YYYY-MM-DD.md` | | `brief` | One-page orientation for humans and coding agents | `docs/project-brief.md` | | anything else or empty | Pick by the defaults below | as above |

The rest of the argument is the path (default: project root). When no mode is given, take the first rule that matches: (1) a directory or system path below the root means **architecture**; (2) a `.gameforge/project.json` phase of `concept` or `prototype`, or a jam-sized build, means **concept**; (3) no GDD in `design/` means **design**; (4) otherwise **architecture**. State the choice in Assumptions.

Critical rules

1. **Read before writing.** Every claim traces to a file and line, a commit, or a config key. Cite them inline (`player/dash.gd:14`, commit `a3f9b2c`). 2. **Intent over implementation.** "Applies downward force" is code; "the player gets about six frames of coyote time after leaving a ledge, so jumps feel forgiving" is design. Write the second and cite the first. 3. **Label every intent claim.**

• **STATED** -- intent is written down: a code comment, commit message, test name, existing doc.
• **INFERRED** -- strongly implied by behavior and naming.
• **UNVERIFIED** -- plausible but unsupported; the team must confirm.

Guessing intent and presenting it as fact is worse than leaving a gap. 4. **Systems, not files.** Organize by game system (movement, combat, economy, UI). A system that spans five files across three folders is one section with a file list. 5. **Surface inconsistencies.** If movement assumes tiles and collision assumes continuous space, or two save systems exist, that is a headline finding, not a footnote. 6. **Know what you cannot read.** Unreal Blueprints and `.uasset`/`.umap` files are binary; Unity and Godot scenes are text but carry tuned values and wiring. Document what is visible and list the binary or editor-only logic as a limit. 7. **One pipeline, four outputs.** The analysis below is shared; only the output format changes.

Phase 1: Project scan

1. **Engine and version.** `.gameforge/project.json`; else `project.godot`, `ProjectSettings/ProjectVersion.txt`, `*.uproject`, or `package.json` dependencies (`three`, `@react-three/fiber`, `phaser`, `pixi.js`, `kaplay`, `excalibur`, `babylonjs`, `playcanvas`), `Cargo.toml` with `bevy`. Note the language mix (GDScript/C#, C#, C++/Blueprint, TS/JS). 2. **Entry points.** Godot `run/main_scene` and `[autoload]` in `project.godot`; Unity scenes in `ProjectSettings/EditorBuildSettings.asset`; Unreal `GameDefaultMap` and `GlobalDefaultGameMode` in `Config/DefaultEngine.ini`; web `index.html` -> `src/main.*`. 3. **Shape and scale.** Annotated directory tree (two levels), counts of scripts, scenes, assets and tests from Glob. Classify: small (under ~50 scripts), medium, large. For large projects, document the core loop systems fully and the rest at inventory depth; say so. 4. **Existing knowledge.** README, `CLAUDE.md`, `design/`, `docs/`, `progress.md`, `SPEC.md`, `production/session-state/active.md`, code comment density, test presence. 5. **History.** `git log --oneline -50` for the arc of deve