Reverse 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

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, under the code root — src/ Godot, Assets/ Unity, Source/<Module>/ Unreal (.claude/docs/code-root-resolution.md)

• src/gameplay/combat/ → All combat-related code (Godot)
• Assets/Scripts/Core/EventSystem.cs → Specific file (Unity)
• Source/MyGame/Private/AI/ → A module folder (Unreal)
• prototypes/stealth-mech/ → Prototype directory

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys workflow,system_overrides,automation

Automation mode: Resolve modes.automation (project.local.yaml → project.yaml → default collaborative). Every AskUserQuestion call and every file write follows .claude/docs/automation-modes.md (collaborative asks always · guided major-only · autonomous logs and proceeds; automation_always_ask categories always prompt).

Resolved above — use as-is. No block → defaults in .claude/docs/config-resolution.md.

Resolve the workflow tier for the target system: map <path> to a system name, then use the system_overrides row for that system if the block above lists one, else the project workflow value. It sets how much document is generated — see Phase 5. Semantics of each tier are in .claude/docs/workflow-modes.md.

Resolve the tier — do not assume it. "Resolve the tier per workflow-modes.md" with no bootstrap names a resolution it gives no way to perform: that document defines what each tier means, but it cannot say what this project is set to. The consequence is large here — at full this skill writes an 8-section GDD and at minimal a one-page brief, so a wrong tier produces the wrong artifact entirely.

Examples:

/reverse-document design src/gameplay/magic-system
/reverse-document architecture Source/MyGame/Private/EntityComponent
/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 3b: Sufficiency Check — is there enough here to document?

Run this before Phase 4, and stop here if it fails. This skill infers a design from an implementation, so when the implementation is thin there is nothing to infer from — and the template below will happily accept invented content, because every section of it is mandatory.

Count what Phase 2 actually found:

If all three counts are zero, or the target path holds fewer than ~20 lines of non-boilerplate code, stop and say so:

"[path] does not contain enough implementation to reverse-document. Found: [N] mechanics, [N] formulas, [N] tuning values. Reverse-documentation infers design from behaviour; with no behaviour to read, anything I produce would be invention wearing the format of a design document. If the design exists only in your head, /design-system [name] is the skill that captures it — it asks rather than infers."

Do not proceed on a partial count by filling the rest. A path with two mechanics and no formulas gets a document with two mechanics and an explicit FORMULAS DISCOVERED: none found in the source — see Phase 4.

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?

Every section above may be empty, and an empty one must say so. Write none found in the source under the heading — never omit the heading (which reads as "not looked for") and never populate it from what a system like this usually has. The bracketed rows are shapes, not quotas: a source with one mechanic yields one row, not four.

This matters more here than in a report, because the output of this skill is not a report — it is a design document, and /design-review, /create-epics and /create-stories will read it as a statement of authored intent. A fabricated formula in a GDD does not stay a documentation error; it becomes a requirement, and then a story, and then code written to satisfy it.

Wait for user to clarify intent before drafting.

If the user does not answer the UNCLEAR INTENT AREAS questions, do not draft the resolved version anyway. Those questions exist because code cannot tell you why — it records what was built, never what was intended, and the gap between them is the entire content of a design document. Unanswered items are carried into the draft verbatim as open questions, in the document, marked INTENT UNKNOWN — inferred from implementation, not confirmed. An inferred intent presented as a settled one is the failure mode of this whole skill.