ccgs-reverse-document

name	ccgs-reverse-document
description	Generate design or architecture documents from existing implementation — works backwards from code or prototypes to create a missing GDD section, ADR, or concept doc. Use for undocumented features or inherited code.

Cowork Adaptation Notes (read first)

Converted from Claude Code Game Studios (github.com/Donchitos/Claude-Code-Game-Studios) for Claude Cowork. Apply these substitutions when following the instructions below:

1. Agents: Named agents (e.g. game-designer, unity-specialist) are not Cowork subagents. When told to "spawn an agent via Task", read the matching file in this skill's bundled roles/ folder and either (a) launch a general-purpose subagent via the Agent tool with that role file's content prepended to the brief, or (b) adopt the role inline and continue. If a role file is not bundled, adopt the role inline from its name.
2. Project paths: design/, docs/, production/, src/ live in the user's connected project folder. Create them there as needed. Bundled reference docs are in this skill's refs/ and templates/ folders.
3. Slash commands: /skill-name means "the ccgs-skill-name skill". Installed set: start, brainstorm, map-systems, design-system, consistency-check, create-architecture, create-epics, create-stories, story-readiness, sprint-plan, dev-story, code-review, story-done, propagate-design-change, reverse-document. If a referenced skill is NOT in this set, tell the user it isn't installed and offer to do the equivalent steps manually.
4. Hooks: Claude Code hooks do not run in Cowork. Do their checks manually: validate JSON files you write, follow naming conventions, no hardcoded magic numbers, and update production/session-state/active.md at the start and end of each work session.
5. Engine: This project targets Unity (C#). Ignore Godot and Unreal routing rows.
6. Review mode: If production/review-mode.txt doesn't exist in the project folder, default to lean.

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...]

Phase 8: Flag Follow-Up Work

After writing, suggest next steps:

✅ Written to design/gdd/combat-system.md

FOLLOW-UP RECOMMENDED:
1. Run /balance-check on combat formulas (exponential scaling concern)
2. Create ADR for stamina system architecture decision
3. Implement missing edge cases:
   - Stamina depletion mid-combo behavior
   - Stagger state during dodge
4. Extend design doc when weapon variety is implemented

Would you like me to tackle any of these now?

Template Selection Logic

If analyzing...	Use template...	Because...
src/gameplay/*	design-doc-from-implementation.md	Gameplay mechanics → GDD
src/core/*, src/ai/*	architecture-doc-from-code.md	Core systems → ADR
prototypes/*	concept-doc-from-prototype.md	Experiments → concept doc
src/networking/*	architecture-doc-from-code.md	Technical systems → ADR
src/ui/*	design-doc-from-implementation.md	UI/UX → design spec

Example Session: Reverse-Document a System

User: /reverse-document design src/gameplay/[system]

Agent: I'll analyze your [system] implementation to create a design doc.
       [Reads code, discovers mechanics, formulas]

Agent: I've analyzed src/gameplay/[system]/. Here's what I found:
       [Shows mechanics, formulas, unclear areas]

       Before drafting, could you clarify:
       1. [Resource] system intent?
       2. Is [mechanic] a core pillar?
       3. [Value] scaling — intentional or needs tuning?

User: 1. [Resource] is for pacing, prevent [unwanted behavior]
      2. [Mechanic] is core — I want [design intent]
      3. Yeah, exponential is too much, should be linear

Agent: Perfect, that clarifies the vision. Let me draft the design doc.
       [Shows draft with clarified intent]

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

User: Yes, write it.

Agent: ✅ Written to design/gdd/[system-name].md
       ✅ Marked as [REVERSE-DOCUMENTED]
       ✅ Flagged [value] scaling for rebalancing

       Next steps:
       - Update [formula] to [corrected scaling]
       - Run /balance-check to validate [curve]
       - Document [mechanic] as core pillar in game-pillars.md

Collaborative Protocol

This skill follows the collaborative design principle:

1. Analyze First: Read code, understand implementation
2. Question Intent: Ask about "why", not just "what"
3. Present Findings: Show discoveries, highlight unclear areas
4. User Clarifies: Separate intent from accidents
5. Draft Document: Create doc based on reality + intent
6. Show Draft: Display key sections, explain additions
7. Get Approval: "May I write to [filepath]?" On approval: Verdict: COMPLETE — document generated. On decline: Verdict: BLOCKED — user declined write.
8. Flag Follow-Up: Suggest related work, don't auto-execute

Never assume intent. Always ask before documenting "why".