/reverse-document

name: reverse-document
type: workflow
description: "Generates missing design or architecture documentation by working backwards from existing code or prototypes. Use when documentation is missing for existing code or when the user mentions documenting existing implementation or reverse engineering docs."
argument-hint: "<type> <path> (e.g., 'design src/api/auth' or 'architecture src/core')"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Bash
effort: 3
when_to_use: "Use when documentation is missing for existing code, a feature was built without a design doc, or the user needs to formalize an existing implementation into design or architecture documentation."

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?"

**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?"
• "Users seem to exploit the grappling hook for speed. Feature or bug?"

4. Present Findings

Before drafting, show what you discovered:

I've analyzed src/api/auth/. Here's what I found:

MECHANICS IMPLEMENTED:
- 3-hit combo system with timing windows
- Guard-break mechanic (heavy attack vs blocking enemy)
- Stamina system (depletes on attack/dodge, regens when idle)
- Stagger system (builds up, triggers vulnerable state)

FORMULAS DISCOVERED:
- Damage = Base * (1 + StrengthScaling * Level)
- Stagger buildup = AttackStaggerValue / (Enemy.Poise * 0.5)
- Stamina cost = BaseStaminaCost * (1 - EfficiencyBonus)

UNCLEAR INTENT AREAS:
1. Stamina system — pacing or resource management?
2. Stagger — core pillar or supporting feature?
3. Damage scaling — power fantasy or needs tuning?

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

Wait for user to clarify intent before drafting.

5. Draft Document Using Template

Based on type, use appropriate template:

| Type | Template | Output Path | |------|----------|-------------| | `design` | `templates/design-doc-from-implementation.md` | `design/docs/[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)

6. Show Draft and Request Approval

**Collaborative protocol**:

I've drafted the combat system design doc based on your code and clarifications.

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

ADDITIONS I MADE:
- Documented stamina as "pacing mechanic" per your clarification
- Added edge cases not in code (what if stamina hits 0 mid-combo?)
- Flagged balance concern: exponential damage scaling at high levels

SECTIONS MARKED AS INCOMPLETE:
- "Enemy AI interaction with stagger" (not fully implemented yet)
- "Weapon variety and scaling" (only sword implemented so far)

May I write this to design/docs/combat-system.md?

Wait for approval. User may request changes before writing.

7. Write Document with Metadata

When approved, write the file with special markers:

---
status: reverse-documented
date: 2026-02-13
verified-by: [User name]
---

# Combat S