reverse-document
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseReverse 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
阶段1：解析参数
Format:
/reverse-document <type> <path>Type options:
- → Generate a game design document (GDD section)
design - → Generate an Architecture Decision Record (ADR)
architecture - → Generate a concept document from prototype
concept
Path: Directory or file to analyze
- → All combat-related code
src/gameplay/combat/ - → Specific file
src/core/event-system.cpp - → Prototype directory
prototypes/stealth-mech/
Examples:
bash
/reverse-document design src/gameplay/magic-system
/reverse-document architecture src/core/entity-component
/reverse-document concept prototypes/vehicle-combat格式：
/reverse-document <类型> <路径>类型选项：
- → 生成游戏设计文档（GDD章节）
design - → 生成架构决策记录（ADR）
architecture - → 基于原型生成概念文档
concept
路径：待分析的目录或文件
- → 所有战斗相关代码
src/gameplay/combat/ - → 指定文件
src/core/event-system.cpp - → 原型目录
prototypes/stealth-mech/
示例：
bash
/reverse-document design src/gameplay/magic-system
/reverse-document architecture src/core/entity-component
/reverse-document concept prototypes/vehicle-combatPhase 2: Analyze Implementation
阶段2：分析实现
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
读取并理解代码/原型：
针对设计文档（GDD）：
- 识别机制、规则、公式
- 提取游戏数值（伤害、冷却时间、范围）
- 梳理状态机、能力系统、成长体系
- 检测代码中处理的边缘情况
- 映射依赖关系（哪些系统存在交互？）
针对架构文档（ADR）：
- 识别设计模式（ECS、单例、观察者等）
- 理解技术决策（线程处理、序列化等）
- 映射依赖与耦合关系
- 评估性能特征
- 梳理约束条件与权衡方案
针对概念文档（原型分析）：
- 识别核心机制
- 提炼涌现式游戏玩法
- 记录有效与无效的部分
- 总结技术可行性见解
- 记录玩家体验/核心爽点
Phase 3: Ask Clarifying Questions
阶段3：提出澄清问题
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?"
不要仅描述代码。要询问设计意图：
设计类问题：
- "我发现一个[资源]系统会在[操作]中消耗。这是为了：
- 节奏控制（防止滥用）？
- 资源管理（增加策略深度）？
- 还是其他目的？"
- "[机制]看起来是核心内容。它是核心支柱功能，还是辅助特性？"
- "[数值]随[因子]呈指数级增长。这是有意设计，还是需要重新平衡？"
架构类问题：
- "你使用了服务定位器模式。选择该模式是为了：
- 可测试性（模拟依赖）？
- 解耦（减少硬引用）？
- 还是继承自现有代码？"
- "我看到使用手动内存管理而非智能指针。是出于性能要求，还是遗留代码原因？"
概念类问题：
- "原型更侧重潜行而非战斗。这是预期的核心方向吗？"
- "玩家似乎利用抓钩来提升移动速度。这是特性还是BUG？"
Phase 4: Present Findings
阶段4：展示分析结果
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.
起草文档前，先展示发现的内容：
我已分析[path]/目录。以下是我的发现：
已实现的机制：
- [机制A]，具备[属性]（如时间窗口、冷却时间）
- [机制B]（如两种状态间的交互）
- [资源]系统（在[操作]时消耗，在[条件]下恢复）
- [状态]系统（累积后触发[效果]）
发现的公式：
- [输出] = [使用已发现变量的公式]
- [次要输出] = [公式]
意图不明确的区域：
1. [资源]系统 — 是节奏控制还是资源管理？
2. [机制] — 核心支柱还是辅助特性？
3. [数值]缩放 — 有意设计还是需要调整？
在起草设计文档前，能否请你澄清这些问题？等待用户澄清意图后再起草文档。
Phase 5: Draft Document Using Template
阶段5：使用模板起草文档
Based on type, use appropriate template:
| Type | Template | Output Path |
|---|---|---|
| | |
| | |
| | |
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
阶段6：展示草稿并请求批准
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.
协作流程：
我已基于你的代码和澄清内容起草了[system-name]设计文档。
[展示关键章节：概述、机制、公式、设计意图]
我补充的内容：
- 根据你的澄清，将[机制]记录为「[意图]」
- 添加了代码中未覆盖的边缘情况（例如：[资源]在[操作]中途耗尽时的行为？）
- 标记了平衡问题：[缩放类型]在[边界条件]下的缩放
标记为未完成的章节：
- 「[系统]与[其他系统]的交互」（尚未完全实现）
- 「[变体或特性]」（仅实现了[子集]）
我可以将文档写入design/gdd/[system-name].md吗？等待批准。用户可能会要求修改后再写入。
Phase 7: Write Document with Metadata
阶段7：写入带元数据的文档
When approved, write the file with special markers:
markdown
---
status: reverse-documented
source: [path/]
date: [today]
verified-by: [User name]
---获得批准后，写入带有特殊标记的文件：
markdown
---
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...]
undefined注意：本文档由现有实现反向生成。 它记录了当前行为和已澄清的设计意图。部分章节可能因实现不完整或意图不明确而存在缺失。
[文档其余内容...]
undefinedPhase 8: Flag Follow-Up Work
阶段8：标记后续工作
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?写入完成后，建议后续步骤：
✅ 已写入design/gdd/combat-system.md
建议后续工作：
1. 对战斗公式运行/balance-check（指数级缩放问题）
2. 为 stamina 系统创建架构决策记录（ADR）
3. 实现缺失的边缘情况：
- 连招中途 stamina 耗尽的行为
- 闪避时的 stagger 状态
4. 武器多样性实现后扩展设计文档
你希望我现在处理其中哪一项？Template Selection Logic
模板选择逻辑
| If analyzing... | Use template... | Because... |
|---|---|---|
| design-doc-from-implementation.md | Gameplay mechanics → GDD |
| architecture-doc-from-code.md | Core systems → ADR |
| concept-doc-from-prototype.md | Experiments → concept doc |
| architecture-doc-from-code.md | Technical systems → ADR |
| design-doc-from-implementation.md | UI/UX → design spec |
| 分析对象... | 使用模板... | 原因... |
|---|---|---|
| design-doc-from-implementation.md | 游戏玩法机制 → GDD |
| architecture-doc-from-code.md | 核心系统 → ADR |
| concept-doc-from-prototype.md | 实验项目 → 概念文档 |
| architecture-doc-from-code.md | 技术系统 → ADR |
| design-doc-from-implementation.md | UI/UX → 设计规范 |
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用户：/reverse-document design src/gameplay/[system]
Agent：我将分析你的[system]实现以生成设计文档。
[读取代码，发现机制、公式]
Agent：我已分析src/gameplay/[system]/目录。以下是我的发现：
[展示机制、公式、不明确区域]
在起草前，能否请你澄清：
1. [资源]系统的设计意图？
2. [机制]是核心支柱功能吗？
3. [数值]缩放 — 有意设计还是需要调整？
用户：1. [资源]用于节奏控制，防止[不当行为]
2. [机制]是核心功能 — 我希望达到[设计意图]
3. 是的，指数级缩放太夸张了，应该改成线性
Agent：完美，这明确了设计方向。我现在起草设计文档。
[展示包含已澄清意图的草稿]
我可以将文档写入design/gdd/[system-name].md吗？
用户：可以，写入吧。
Agent：✅ 已写入design/gdd/[system-name].md
✅ 标记为[REVERSE-DOCUMENTED]
✅ 标记[数值]缩放需要重新平衡
后续步骤：
- 将[公式]更新为[修正后的缩放方式]
- 运行/balance-check验证[曲线]
- 在game-pillars.md中将[机制]记录为核心支柱Collaborative Protocol
协作协议
This skill follows the collaborative design principle:
- Analyze First: Read code, understand implementation
- Question Intent: Ask about "why", not just "what"
- Present Findings: Show discoveries, highlight unclear areas
- User Clarifies: Separate intent from accidents
- Draft Document: Create doc based on reality + intent
- Show Draft: Display key sections, explain additions
- Get Approval: "May I write to [filepath]?" On approval: Verdict: COMPLETE — document generated. On decline: Verdict: BLOCKED — user declined write.
- Flag Follow-Up: Suggest related work, don't auto-execute
Never assume intent. Always ask before documenting "why".
该技能遵循协作设计原则：
- 先分析：读取代码，理解实现细节
- 询问意图：关注「为什么」，而非仅「是什么」
- 展示发现：呈现分析结果，突出不明确区域
- 用户澄清：区分设计意图与意外情况
- 起草文档：基于实际实现+设计意图创建文档
- 展示草稿：展示关键章节，说明补充内容
- 获取批准：询问「我可以写入[文件路径]吗？」获得批准则：结果完成——文档生成。被拒绝则：结果阻塞——用户拒绝写入。
- 标记后续：建议相关工作，不自动执行
永远不要假设意图。记录「为什么」前务必先询问。