Reverse Document

Reverse Document:

Generate Design and Architecture Docs from Existing Code

What Is This?

The Reverse Document skill is a diagnostic utility designed for the Happycapy Skills platform. It automates the generation of design or architecture documentation from existing implementation artifacts, such as codebases, prototypes, or system directories. Instead of starting with planning documents, this skill works backwards: it analyzes your code or prototypes and synthesizes clear, structured documentation that describes the design rationale, architecture decisions, or conceptual purpose behind what has already been built.

The skill supports three main documentation types:

• Design: Produces a Game Design Document (GDD) section based on gameplay or feature code.
• Architecture: Generates an Architecture Decision Record (ADR) for technical structures or system-level code.
• Concept: Creates a concept document from prototype directories.

This approach is particularly useful for teams or individuals who have code but lack formal documentation, whether due to rapid prototyping, inherited legacy code, or agile workflows where features were built before their plans were formalized.

Why Use It?

Codebases often evolve faster than documentation can keep up. Many teams find themselves with fully functional systems but little or no high-level documentation explaining the "why" behind technical decisions, gameplay mechanics, or architectural structures. This lack of documentation can lead to:

• Increased onboarding time for new developers
• Loss of design rationale over time
• Difficulty in communicating intent or extracting reusable patterns

The Reverse Document skill addresses these issues by:

• Automating the initial generation of missing docs from code or prototypes
• Ensuring that documentation reflects actual implementation, not just intentions
• Providing a foundation for further manual documentation refinement

By bridging the gap between implementation and planning, this skill helps teams maintain cleaner, more maintainable, and more understandable projects.

How to Use It

Command Format

The skill is invoked using the following syntax in your Happycapy environment:

/reverse-document <type> <path>

• <type>: The kind of document you want to generate. Choose one of:
  • design: For gameplay or feature design docs
  • architecture: For technical or system-level architecture docs
  • concept: For conceptual documents from prototypes
• <path>: The file or directory to analyze. This could be a specific source file or an entire feature directory.

Examples:

/reverse-document design src/gameplay/magic-system
/reverse-document architecture src/core/entity-component
/reverse-document concept prototypes/vehicle-combat

Step-by-Step Workflow

1. Parse Arguments: The skill reads the type and path. It validates the input to ensure the target exists and the type is supported.
2. Analyze: The skill scans the specified code or prototype directory, extracting structure, logic, and implied design decisions.
3. Generate Documentation: Based on the analysis, it creates a structured document appropriate to the type:
   • For design, it produces a GDD section (objective, mechanics, edge cases).
   • For architecture, it outputs an ADR (context, decision, consequences).
   • For concept, it creates a high-level concept doc (purpose, features, constraints).
4. Output: The generated documentation is saved or displayed for review.

Sample Output

Suppose you run:

/reverse-document architecture src/core/event-system.cpp

The skill might generate the following ADR excerpt:

## Architecture Decision Record:

Event System

## Context
The `event-system.cpp` module provides a decoupled communication mechanism for core engine components.

## Decision
We implemented a publish-subscribe event system using observer pattern to allow modules to communicate without direct dependencies.

## Consequences
- Simplifies adding new event types
- Reduces coupling between core subsystems
- Introduces slight performance overhead due to event dispatch

When to Use It

Use the Reverse Document skill in the following scenarios:

• Post-Implementation Documentation: After building a feature or system without a prior design doc.
• Onboarding: When inheriting a legacy codebase that lacks adequate documentation.
• Prototyping: To formalize prototypes that are transitioning into production features.
• Design Recovery: When you need to capture the reasoning behind existing code that has evolved over time.
• Compliance or Auditing: To generate documentation for auditing or knowledge transfer purposes.

This skill is not intended for generating documentation from scratch before any code exists. It is specifically for reverse-engineering docs from what has already been built.

Important Notes

• Scope: The skill analyzes code and prototypes only within the given path. For comprehensive documentation, you may need to run it on multiple directories.
• Automation Limitations: While the generated documentation provides a strong starting point, manual review and refinement are recommended for completeness and clarity.
• No Specialist Delegation: This is a read-only diagnostic skill. It does not delegate to specialist agents or make code changes.
• Supported Tools: The skill is allowed to read, glob, grep, write, edit, and use Bash utilities for file analysis.
• No Language Support Beyond English: Output is strictly in English to maintain consistency and clarity.
• Best Practices: Use the generated docs as a living foundation. Regularly update them as the implementation evolves.

By leveraging Reverse Document, teams can systematically bridge the gap between code and documentation, ensuring that project knowledge remains accessible and maintainable throughout the software lifecycle.