reverse-document

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

1. Parse Arguments

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

Type options:

• design → Generate a product design document (PRD section)
• architecture → Generate an Architecture Decision Record (ADR)
• concept → Generate a concept document from prototype

Path: Directory or file to analyze

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

Examples:

/reverse-document design src/api/payment
/reverse-document architecture src/core/entity-component
/reverse-document concept prototypes/vehicle-combat

2. Analyze Implementation

Read and understand the code/prototype:

For design docs (PRD):

• Identify mechanics, rules, formulas
• Extract business logic 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 business patterns
• Note what worked vs what didn't
• Find technical feasibility insights
• Document user fantasy / feel

3. Ask Clarifying Questions (Collaborative Protocol)

DO NOT just describe the code. ASK about intent:

Design questions:

• "I see a stamina system that depletes during combat. Was this for:
  • Pacing (prevent spam)?
  • Resource management (strategic depth)?
  • Or something else?"
• "The stagger mechanic seems central. Is this a core pillar, or supporting feature?"
• "Damage scales exponentially with level. Intentional power fantasy, or needs rebalancing?"