/reverse-document

name: reverse-document
description: "Generate design or architecture documents from existing implementation. Works backwards from code/prototypes to create missing planning docs."
argument-hint: "<type> <path> (e.g., 'design src/gameplay/combat' or 'architecture src/core')"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Bash
model: sonnet
# Read-only diagnostic skill — no specialist agent delegation needed

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**: `/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**:

/reverse-document design src/gameplay/magic-system
/reverse-document architecture src/core/entity-component
/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

Phase 3: Ask Clarifying Questions

**DO NOT** just describe the code. **ASK** about intent:

**Design questions**:

• "I see a [resource] system that depletes during [activity]. Was this for:
• Pacing (prevent spam)?
• Resource management (strategic depth)?
• Or something else?"
• "The [mechanic] seems central. Is this a core pillar, or supporting feature?"
• "[Value] scales exponentially with [factor]. Intentional design, or needs rebalancing?"

**Architecture questions**:

• "You're using a service locator pattern. Was this chosen for:
• Testability (mock dependencies)?
• Decoupling (reduce hard references)?
• Or inherited from existing code?"
• "I see manual memory management instead of smart pointers. Performance requirement, or legacy?"

**Concept questions**:

• "The prototype emphasizes stealth over combat. Is that the intended pillar?"
• "Players seem to exploit the grappling hook for speed. Feature or bug?"

Phase 4: Present Findings

Before drafting, show what you discovered:

I've analyzed [path]/. Here's what I found:

MECHANICS IMPLEMENTED:
- [mechanic-a] with [property] (e.g. timing windows, cooldowns)
- [mechanic-b] (e.g. interaction between two states)
- [resource] system (depletes on [action], regens on [condition])
- [state] system (builds up, triggers [effect])

FORMULAS DISCOVERED:
- [Output] = [formula using discovered variables]
- [Secondary output] = [formula]

UNCLEAR INTENT AREAS:
1. [Resource] system — pacing or resource management?
2. [Mechanic] — core pillar or supporting feature?
3. [Value] scaling — intentional design or needs tuning?

Before I draft the design doc, could you clarify these points?

Wait for user to clarify intent before drafting.

Phase 5: Draft Document Using Template

Based on type, use appropriate template:

| Type | Template | Output Path | |------|----------|-------------| | `design` | `templates/design-doc-from-implementation.md` | `design/gdd/[system-name].md` | | `architecture` | `templates/architecture-doc-from-code.md` | `docs/architecture/[decision-name].md` | | `concept` | `templates/concept-doc-from-prototype.md` | `prototypes/[name]/CONCEPT.md` or `design/concepts/[name].md` |

**Draft structure**:

• Capture **what exists** (mechanics, patterns, implementation)
• Document **why it exists** (intent clarified with user)
• Identify **what's missing** (edge cases not handled, gaps in design)
• Flag **follow-up work** (balance tuning, missing features)

Phase 6: Show Draft and Request Approval

**Collaborative protocol**:

I've drafted the [system-name] design doc based on your code and clarifications.

[Show key sections: Overview, Mechanics, Formulas, Design Intent]

ADDITIONS I MADE:
- Documented [mechanic] as "[intent]" per your clarification
- Added edge cases not in code (e.g., what if [resource] hits 0 mid-[action]?)
- Flagged balance concern: [scaling type] scaling at [boundary condition]

SECTIONS MARKED AS INCOMPLETE:
- "[System] interaction with [other-system]" (not fully implemented yet)
- "[Variant or feature]" (only [subset] implemented so far)

May I write this to design/gdd/[system-name].md?

Wait for approval. User may request changes before writing.

Phase 7: Write Document with Metadata

When approved, write the file with special markers:

---
status: reverse-documented
source: [path/]
date: [today]
verified-by: [User name]
---

# [System Name] Design

> **Note**: This document was reverse-engineered from the existing implementation.
> It captures current behavior and clarified design intent. Some sections may be
> incomplete where implementation is partial or intent was unclear.

[Rest of document...]

Pha