# SophClaw Skill Creator — 路径 B：补全 design.md

从已有代码逆向分析，为缺少 `design.md` 的 skill 补全设计文档。

流程：逆向分析 → 对齐确认 → 生成文档。

```dot
digraph design_backfill {
    rankdir=TB;

    start [label="用户要求补全 design.md", shape=oval];
    identify [label="第一步：确定目标 skill\n确认 skill 名称", shape=box];
    read [label="第二步：阅读已有代码\nskill.json + SKILL.md + 脚本 + 资源", shape=box];
    draft [label="第三步：逆向整理\n从代码中还原需求和方案", shape=box];
    discuss [label="第四步：逐节确认\n与用户对齐理解", shape=box];
    write [label="第五步：写入 design.md", shape=box];
    done [label="完成 ✅", shape=oval];

    start -> identify;
    identify -> read;
    read -> draft;
    draft -> discuss;
    discuss -> draft [label="用户纠正/补充"];
    discuss -> write [label="用户确认"];
    write -> done;
}
```

## 第一步：确定目标 skill

用户可能说"给 restore-state 补一个 design.md"、"补充 XXX 的设计文档"。先确认：

1. skill 名称是什么？
2. 确认路径 `<skills_dir>/<name>/` 存在（用 `ls <skills_dir>/<name>/` 验证）
3. 确认 `design.md` 确实不存在（不覆盖已有文件）

## 第二步：阅读已有代码

完整读取目标 skill 的以下文件：

| 文件 | 获取什么信息 |
|------|-------------|
| `<skills_dir>/<name>/skill.json` | name、version、types、displayName、description、changelog |
| `<skills_dir>/<name>/src/SKILL.md` | 触发描述、前置检查、用法、输出格式、异常处理 |
| `<skills_dir>/<name>/src/scripts/*.py` | 核心逻辑、关键设计决策、配置常量 |
| `<skills_dir>/<name>/src/pyproject.toml` | 依赖、Python 版本要求 |
| `<skills_dir>/<name>/src/references/*` | 参考文档 |
| `<skills_dir>/<name>/src/assets/*` | 模板/资源文件 |

**这一步不问用户任何问题**，全靠阅读代码收集信息。

## 第三步：逆向整理

从代码中还原设计文档所需的内容：

**还原需求说明**（从 skill.json + SKILL.md）：
- 功能描述 ← SKILL.md 的功能说明
- 触发场景 ← SKILL.md 的 description + 触发条件描述
- 输入/输出约定 ← SKILL.md 的输入输出描述 + 脚本的 exit code 逻辑

**还原方案设计**（从脚本代码 + 目录结构）：
- 目录结构 ← `ls` 查看实际文件树
- 是否需要脚本及理由 ← 存在 `src/scripts/` 则"需要"
- SKILL.md 关键设计决策 ← 代码中的硬编码常量、特殊处理逻辑、注释说明
- 注意事项 ← SKILL.md 的异常处理表 + 脚本的错误分支

**还原测试用例**（从 SKILL.md 的异常处理表 + 脚本边界逻辑）：
- 正常场景 ← SKILL.md 的用法示例
- 异常场景 ← SKILL.md 的异常处理表 + 脚本中的错误处理分支
- 不触发场景 ← 从 description 反推边界（相近但不应触发的场景，如"备份数据"对 restore-state）

## 第四步：逐节确认

将整理好的内容分节呈现给用户，每节确认后再继续下一节：

1. 先呈现「需求说明」，问："功能描述和触发场景我整理得对吗？有没有遗漏或需要补充的？"
2. 再呈现「方案设计」，问："架构和关键设计决策我理解得对吗？"
3. 最后呈现「测试用例」，问："测试用例是否完整？是否需要增删？"

**与路径A的共同点**：都需要与用户对齐，确保理解正确。
**与路径A的不同点**：这里是先基于代码给出初步判断再确认，而非从零开始提问。

## 第五步：写入 design.md

用户逐节确认后，写入 `<skills_dir>/<name>/design.md`。

**格式严格遵循** [references/skill-notes.md](references/skill-notes.md) **§十「design.md 规范」**：

```markdown
# <skill-name> 设计文档

## 一、需求说明
- 功能描述
- 触发场景（用户怎么说话会触发）
- 输入/输出约定
- 上线平台及 type 选择理由

## 二、方案设计
- 目录结构
- 是否需要脚本及理由
- SKILL.md 关键设计决策
- 注意事项

## 三、测试用例
| 编号 | 测试场景 | 触发语句 | 预期匹配 | 预期行为 | 预期输出 |
```

**补充说明**（在规范结构基础上可酌情扩充）：
- 「需求说明」可追加"核心能力""不触发场景"小节，帮助完善边界描述
- 「方案设计」可追加"架构""职责划分"小节，补充架构图和组件分工表
- 以上为可选扩充，规范中的 4 个要点和表头必须保留