用途
devdocs-retrofit 用于将已有工程改造为 DevDocs 流程，或将旧版 DevDocs 迁移到新规范，也可从代码逆向生成结构化文档。
语言规则：支持中英文提问，统一中文回复，使用中文生成文档。
触发条件：
- 用户希望将现有项目适配 DevDocs 流程
- 用户需要标准化项目文档
- 用户要迁移或升级已有 DevDocs 文档
- 项目缺少文档，需要从代码逆向生成
主要能力
项目状态检测
检查 docs/devdocs/ 目录是否存在：不存在则进入新项目改造流程；存在则检查规范符合性，符合当前规范则无需改造，不符合则进入版本迁移流程。
规范符合性检查清单包括：编号体系（F-XXX、US-XXX、AC-XXX，必须）、测试编号（UT-XXX、IT-XXX、E2E-XXX，必须）、追溯矩阵（F → US → AC → 测试映射，必须）、文件命名（01-requirements.md、03-test-cases.md 等，必须）、章节完整性（各文档必要章节，必须）、Skill 协作（标注协作 Skill，建议）。
版本迁移流程
当检测到已有 DevDocs 文档但不符合当前规范时执行：
- Step M1 规范检查：扫描现有 DevDocs 文档，输出规范检查报告（文件、状态、问题）。
- Step M2 生成差异清单：列出编号体系、文件结构、追溯矩阵、章节补充等需要迁移的内容。
- Step M3 用户确认：使用 AskUserQuestion 展示迁移计划，提供完整迁移（推荐）、选择性迁移、仅生成报告三个选项。
- Step M4 迁移文档：为现有内容添加编号、使用 git mv 重命名文件以保留历史、生成追溯矩阵。
新项目改造流程
当项目没有 DevDocs 文档时执行：
- Step 1 扫描项目结构：扫描 docs/、doc/、documentation/、README.md、CHANGELOG.md、design/、architecture/、tests/、test/、tests/ 等常见位置。
- Step 2 自动识别文档：按需求文档、系统设计、测试用例、开发任务四个阶段，依据关键词和常见文件名识别。
- Step 3 用户确认：展示文档识别结果，提供确认识别结果、手动指定文档、代码逆向推导三个选项。
- Step 4 代码逆向推导（可选）：从路由/页面、API 端点、测试描述、测试断言推导功能模块（F-XXX）、用户故事（US-XXX）、验收标准（AC-XXX）及测试用例（UT/IT/E2E-XXX），推导内容标注 [从代码推导]。
- Step 5 生成 DevDocs 文档：按规范生成完整文档目录。
改造报告
改造完成后必须生成 00-retrofit-report.md，包含改造概览、文档状态、编号分配、待完善项、下一步建议。
使用方式
扫描项目结构和检测状态后，必须使用 EnterPlanMode 呈现改造策略，等用户审批后再生成/更新文档。
Plan 必须包含：
- 新项目改造：项目概况（类型、技术栈、规模）→ 文档识别结果 → 改造方式（文档转换/逆向推导/混合）→ 推导范围和粒度 → 预估产出（F/US/AC 数量）→ 风险与注意
- 版本迁移：规范检查结果 → 迁移动作清单（含影响范围和风险）→ 迁移方式（完整/选择性/仅报告）
适用场景
- 项目缺少文档，需要从代码逆向生成
- 需要标准化项目文档
- 迁移或升级已有 DevDocs 文档
- 将现有项目适配 DevDocs 流程
限制
阶段边界约束（最高优先级）：
- 本 Skill 仅产出/更新 DevDocs 文档，严禁编写或生成任何实现代码
- Write 工具仅用于写入 docs/devdocs/ 下的 Markdown 文档
- 编码实现由 /devdocs-dev-workflow 负责，本 Skill 不涉及
Plan 模式约束：扫描项目 + 检测状态后必须进入 Plan 模式；Plan 必须包含改造策略和预估产出（新项目）或迁移动作清单（版本迁移）；用户审批 Plan 后才能开始文档改造；用户要求调整时更新 Plan 后重新审批。
检测约束：必须先检测项目状态；必须扫描常见文档目录；识别结果必须让用户确认。
迁移约束：迁移前必须生成差异清单；迁移前必须用户确认；文件重命名必须使用 git mv；不得删除原有文档的有效内容。
编号约束：必须为所有功能点分配 F-XXX 编号；必须为所有用户故事分配 US-XXX 编号；必须为所有验收标准分配 AC-XXX 编号；必须为所有测试用例分配 UT/IT/E2E-XXX 编号；编号必须连续，不得跳号。
输出约束：输出目录统一为 docs/devdocs/；文件命名遵循 DevDocs 规范；必须生成改造报告；逆向推导内容必须标注 [从代码推导]。
输出文件
docs/devdocs/ 目录下包括：00-retrofit-report.md（改造报告）、01-requirements.md（需求文档，含编号）、02-system-design.md（系统设计）、02-system-design-api.md（API 设计，如需要）、03-test-cases.md（测试用例概览 + 追溯矩阵）、03-test-unit.md（单元测试，含 UT-XXX）、03-test-integration.md（集成测试，含 IT-XXX）、03-test-e2e.md（E2E 测试，含 E2E-XXX）、04-dev-tasks.md（开发任务，含 T-XX）。
Skill 协作
- 需求审查：/devdocs-requirements
- 设计审查：/devdocs-system-design
- 测试用例：/devdocs-test-cases
- 新增功能：/devdocs-feature
- Bug 修复：/devdocs-bugfix
- 测试质量：/testing-guide
- 文件操作：/git-safety（重命名文件时使用 git mv）
错误处理
- 无法识别文档：提示手动指定路径、使用代码逆向推导或使用 /devdocs-requirements 从头创建。
- 项目无文档：推荐使用代码逆向推导功能。
- 迁移冲突：检测编号重复、文件覆盖等冲突并提示处理方式。
子 Agent 摘要格式
当本 Skill 作为子 Agent 运行时，返回结构化摘要，包含 skill、docs_generated、features_extracted、apis_extracted、coverage（requirements/design/tests）、status、output_file 等字段。