reverse-document

Port provenance: adapted from the pinned upstream source at 984023ddac0d5e27624f2baacde6105e45de375f under MIT; see the repository parity ledger for the exact path and blob.

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 doc 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: $ai-game-studio: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

Path: Directory or file to analyze

• src/gameplay/combat/ → All combat-related code
• src/core/event-system.cpp → Specific file
• prototypes/stealth-mech/ → Prototype directory

Examples:

$ai-game-studio:reverse-document design src/gameplay/magic-system
$ai-game-studio:reverse-document architecture src/core/entity-component
$ai-game-studio:reverse-document concept prototypes/vehicle-combat

Phase 2: Analyze Implementation

Read and understand the code/prototype:

For design docs (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