SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsdevdocs-retrofit

devdocs-retrofit

Writing & research

View repository

Updated 10-15 08:13

About this skill

Project Transformation

Transform an existing project into the DevDocs process, or migrate legacy DevDocs to the new specification.

Language Rules

  • Support questions in Chinese and English
  • Unified Chinese responses
  • Generate documentation in Chinese

Trigger Conditions

  • The user wants to adapt an existing project to the DevDocs process
  • The user needs to standardize project documentation
  • The user wants to migrate or upgrade existing DevDocs documentation
  • The project lacks documentation and needs to be reverse-generated from code

Workflow

1. 扫描项目结构
   │
   ▼
2. 检测项目状态
   │
   ├── 无 DevDocs ──────────────────┐
   │                                │
   ├── 有 DevDocs（旧版）────┐      │
   │                         │      │
   └── 有 DevDocs（符合规范）│      │
       → 无需改造            │      │
                             ▼      ▼
3. 进入 Plan 模式 → 呈现改造策略
   │              （改造类型、范围、推导方式、预估工作量）
   ▼
4. 用户审批 Plan → 确认策略或调整
   │
   ▼
5. 退出 Plan 模式 → 生成/更新 docs/devdocs/ 改造文档
   │
   ├── 版本迁移流程          新项目改造流程
   │   ├── 规范检查            ├── 自动识别文档
   │   ├── 生成差异清单        ├── 代码逆向推导（可选）
   │   └── 更新迁移文档        └── 生成 DevDocs 文档
   │
   ▼
6. 生成改造报告

Plan Mode Specification

After scanning the project structure and detecting the status,you must use EnterPlanMode to present the transformation strategy, and generate/update documentation only after the user approves.

The Plan must include

New Project Transformation: Project overview (type, tech stack, scale) → Documentation identification results → Transformation approach (document conversion/reverse derivation/hybrid) → Derivation scope and granularity → Estimated output (number of F/US/AC) → Risks and considerations

Version Migration: Specification check results → Migration action list (including impact scope and risks) → Migration approach (full/selective/report only)

Project Status Detection

Detection Logic

1. 检查 docs/devdocs/ 目录是否存在
   │
   ├── 不存在 → 新项目改造流程
   │
   └── 存在 → 检查规范符合性
       │
       ├── 符合当前规范 → 无需改造
       │
       └── 不符合 → 版本迁移流程

Specification Compliance Checklist

Check Item Check Content Specification Requirement
Numbering System F-XXX, US-XXX, AC-XXX Required
Test Numbering UT-XXX, IT-XXX, E2E-XXX Required
Traceability Matrix F → US → AC → Test mapping Required
File Naming 01-requirements.md, 03-test-cases.md, etc. Required
Section Completeness Required sections of each document Required
Skill Collaboration Annotate collaborating Skills Recommended

Version Migration Process

Executed when existing DevDocs documentation is detected but does not conform to the current specification.

Step M1: Specification Check

Scan existing DevDocs documentation and check specification compliance:

## 规范检查报告

### 检测结果

| 文件 | 状态 | 问题 |
|------|------|------|
| 01-requirements.md | ⚠️ 需迁移 | 缺少 F/US/AC 编号 |
| 02-system-design.md | ✅ 符合 | - |
| 03-test-plan.md | ❌ 需重命名 | 应为 03-test-cases.md |
| 04-dev-tasks.md | ⚠️ 需迁移 | 缺少 T-XX 编号 |

Step M2: Generate Difference List

List in detail the content that needs to be migrated:

## 迁移差异清单

### 编号体系

| 文档 | 当前状态 | 迁移动作 |
|------|----------|----------|
| 01-requirements.md | 无编号 | 为功能点添加 F-001, F-002... |
| 01-requirements.md | 无编号 | 为用户故事添加 US-001, US-002... |
| 01-requirements.md | 无编号 | 为验收标准添加 AC-001, AC-002... |
| 03-test-*.md | 无编号 | 为测试用例添加 UT/IT/E2E-XXX |
| 04-dev-tasks.md | 无编号 | 为任务添加 T-01, T-02... |

### 文件结构

| 当前文件 | 迁移动作 | 目标文件 |
|----------|----------|----------|
| 03-test-plan.md | 重命名 + 拆分 | 03-test-cases.md |
| - | 新建 | 03-test-unit.md |
| - | 新建 | 03-test-integration.md |
| - | 新建 | 03-test-e2e.md |

### 追溯矩阵

| 当前状态 | 迁移动作 |
|----------|----------|
| 不存在 | 在 03-test-cases.md 中新建追溯矩阵章节 |

### 章节补充

| 文档 | 缺失章节 | 迁移动作 |
|------|----------|----------|
| 02-system-design.md | 需求追溯 | 添加第 13 节 |
| 04-dev-tasks.md | Skill 协作约束 | 添加编码约束说明 |

Step M3: User Confirmation

Use AskUserQuestion to present the migration plan:

## 迁移计划确认

检测到当前 DevDocs 文档需要迁移到新规范。

### 迁移内容

1. **编号体系**：为所有功能点、用户故事、验收标准、测试用例添加编号
2. **文件重命名**：03-test-plan.md → 03-test-cases.md
3. **新建追溯矩阵**：建立 F → US → AC → 测试 的追溯关系
4. **章节补充**：补充缺失的规范章节

### 迁移选项

1. **完整迁移**（推荐）- 自动完成所有文档迁移
2. **选择性迁移** - 选择要迁移的文档项
3. **仅生成报告** - 不迁移文档，仅输出差异报告

请选择迁移方式。

Step M4: Migrate Documentation

Numbering Migration

Add numbering to existing content:

### 迁移前
- 用户注册功能
  - 作为新用户，我希望注册账号
  - 验收标准：邮箱格式正确

### 迁移后
- **F-001**: 用户注册功能
  - **US-001**: 作为新用户，我希望注册账号，以便使用系统
  - **AC-001**: 邮箱格式正确时注册成功
  - **AC-002**: 邮箱格式错误时提示错误信息

File Renaming

# 使用 git mv 保留历史
git mv docs/devdocs/03-test-plan.md docs/devdocs/03-test-cases.md

Traceability Matrix Generation

## 追溯矩阵

| 功能点 | 用户故事 | 验收标准 | 单元测试 | 集成测试 | E2E测试 |
|--------|----------|----------|----------|----------|---------|
| F-001 | US-001 | AC-001 | UT-001 | - | E2E-001 |
| F-001 | US-001 | AC-002 | UT-002 | - | E2E-001 |
| F-001 | US-002 | AC-003 | UT-003 | IT-001 | - |

New Project Transformation Process

Executed when the project has no DevDocs documentation.

Step 1: Scan Project Structure

Scan common documentation locations:

# 文档目录
docs/ doc/ documentation/

# 根目录文档
README.md CHANGELOG.md

# 设计文档
design/ architecture/

# 测试文档
tests/ test/ __tests__/

Step 2: Automatically Identify Documentation

Identification Rules

DevDocs Stage Identification Keywords Common File Names
Requirements Document requirement, PRD, 需求, spec *requirement*.md, *prd*.md
System Design design, architecture, 设计, 架构 *design*.md, *architecture*.md
Test Cases test, QA, 测试, case *test*.md, *qa*.md
Development Tasks task, todo, 任务, backlog *task*.md, *todo*.md

Step 3: User Confirmation

## 文档识别结果

| 阶段 | 识别状态 | 识别到的文件 |
|------|----------|--------------|
| 需求文档 | ✅ 已识别 | `docs/requirements.md` |
| 系统设计 | ✅ 已识别 | `docs/architecture.md` |
| 测试用例 | ❌ 未找到 | - |
| 开发任务 | ⚠️ 待确认 | `TODO.md` (相似度 60%) |

### 选项

1. **确认识别结果** - 使用自动识别的映射
2. **手动指定文档** - 提供各阶段文档路径
3. **代码逆向推导** - 从代码分析生成文档（适用于无文档项目）

Step 4: Reverse Derivation from Code (Optional)

When the project lacks documentation, generate documentation from code analysis.

Requirement Derivation

Analysis Target Derived Content Number Assignment
Routes/Pages Functional Modules → F-XXX In module order
API Endpoints Business Operations Assign to F-XXX
Test Descriptions User Stories → US-XXX Grouped by F-XXX
Test Assertions Acceptance Criteria → AC-XXX Grouped by US-XXX

Derivation Example

## 功能清单 [从代码推导]

### F-001: 用户模块

**用户故事**：
- **US-001**: 作为用户，我可以注册新账号
  - 来源：`POST /api/users` + `auth.test.ts`
- **US-002**: 作为用户，我可以登录系统
  - 来源：`POST /api/auth/login`

**验收标准**：
- **AC-001**: 邮箱格式正确时注册成功
  - 来源：`auth.test.ts: "should register with valid email"`
- **AC-002**: 密码少于 6 位时提示错误
  - 来源：`auth.test.ts: "should reject short password"`

Test Case Derivation

Analysis Target Derived Content Number Assignment
Unit Test Files UT-XXX In file order
Integration Test Files IT-XXX In file order
E2E Test Files E2E-XXX In file order 
## 测试用例 [从代码推导]

### 单元测试

| 编号 | 关联 AC | 测试描述 | 来源 |
|------|---------|----------|------|
| UT-001 | AC-001 | should register with valid email | auth.test.ts:12 |
| UT-002 | AC-002 | should reject short password | auth.test.ts:24 |

Step 5: Generate DevDocs Documentation

Generate complete documentation according to the DevDocs specification:

docs/devdocs/
├── 01-requirements.md      # 含 F/US/AC 编号
├── 02-system-design.md     # 含模块-功能点映射
├── 03-test-cases.md        # 含追溯矩阵
├── 03-test-unit.md         # 含 UT-XXX 编号
├── 03-test-integration.md  # 含 IT-XXX 编号
├── 03-test-e2e.md          # 含 E2E-XXX 编号
├── 04-dev-tasks.md         # 含 T-XX 编号
└── 00-retrofit-report.md   # 改造报告

Transformation Report

After the transformation is complete, you must generate 00-retrofit-report.md, including transformation overview, documentation status, number assignment, items to be improved, and next-step recommendations.

For the detailed template, see templates/retrofit-report-template.md。

Key Rules: The transformation is not the end point; you must enter the normal development loop through subsequent Skills. It is recommended to first use /devdocs-requirements --context to supplement background information.

Skill Collaboration

Scenario Collaborating Skill Description
Requirement Review /devdocs-requirements Review the transformed requirement documentation
Design Review /devdocs-system-design Review the system design
Test Cases /devdocs-test-cases Improve test case design
New Features /devdocs-feature Add new features after the transformation
Bug Fixes /devdocs-bugfix Fix issues after the transformation
Test Quality /testing-guide Check test effectiveness
File Operations /git-safety Use git mv when renaming files

Constraints

Phase Boundary Constraints (Highest Priority)

  • This Skill only produces/updates DevDocs documentation, and it is strictly forbidden to write or generate any implementation code
  • The Write tool is only used to write docs/devdocs/ Markdown documents under
  • Coding implementation is handled by /devdocs-dev-workflow , and this Skill does not involve it

Plan Mode Constraints

  • After scanning the project + detecting the status, you must enter Plan mode
  • The Plan must include the transformation strategy and estimated outputs (new project) or a migration action checklist (version migration)
  • Documentation transformation can only begin after the user approves the Plan
  • When the user requests adjustments, update the Plan and re-approve it

Detection Constraints

  • The project status must be detected first (no DevDocs / old version / complies with the specification)
  • Common documentation directories must be scanned
  • The identification results must be confirmed by the user

Migration Constraints

  • A difference list must be generated before migration
  • User confirmation is required before migration
  • File renaming must use git mv
  • The valid content of existing documents must not be deleted

Numbering Constraints

  • All feature points must be assigned F-XXX numbers
  • All user stories must be assigned US-XXX numbers
  • All acceptance criteria must be assigned AC-XXX numbers
  • All test cases must be assigned UT/IT/E2E-XXX numbers
  • Numbers must be consecutive, with no skipped numbers

Output Constraints

  • The output directory is unified as docs/devdocs/
  • File naming follows the DevDocs specification
  • A transformation report must be generated
  • Reverse-derived content must be marked with [从代码推导]

Error Handling

Unable to recognize document

未能自动识别到相关文档。

请选择：
1. 手动指定各阶段文档路径
2. 使用代码逆向推导生成文档
3. 使用 /devdocs-requirements 从头创建

Project has no documentation

当前项目未检测到任何文档。

推荐：使用代码逆向推导功能，从代码自动生成文档。

是否开始代码分析？

Migration conflict

检测到迁移冲突：

| 冲突项 | 说明 | 建议 |
|--------|------|------|
| 编号重复 | F-001 已存在 | 重新分配编号 |
| 文件覆盖 | 03-test-cases.md 已存在 | 备份后覆盖 |

请确认处理方式。

Sub-Agent Summary Format

When this Skill runs as a sub-agent, return the following structured summary:

skill: devdocs-retrofit
docs_generated:
  - docs/devdocs/01-requirements.md
  - docs/devdocs/02-system-design.md
features_extracted: X
apis_extracted: X
coverage:
  requirements: "XX%"
  design: "XX%"
  tests: "XX%"
status: completed
output_file: docs/devdocs/00-retrofit-report.md

Output Files

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）