# 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/` 则"需要"
- 架构 ← 从脚本主流程提取：入口 → 参数解析 → 核心逻辑 → 分支/循环（如轮询）→ 成功/失败出口，用 ASCII 流程图表示
- 职责划分 ← 整理各文件/模块的职责分工，生成组件职责表
- 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 选择理由

## 二、方案设计
- 目录结构
- 是否需要脚本及理由
- 架构（ASCII 流程图，展示数据流向和关键分支）
- 职责划分（组件职责表，逐一说明各文件/模块的职责）
- SKILL.md 关键设计决策（决策项 + 理由，帮助维护者理解 WHY）
- 注意事项

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

> **架构流程图**：使用 ASCII 框图展示核心流程，包含关键分支、循环（如轮询）、成功/失败路径。接手者应能在不读代码的情况下理解整体数据流。
>
> **关键设计决策**：每条决策需包含「是什么」+「为什么」，帮助维护者理解取舍而非仅知道配置值。
>
> **注意事项**：覆盖运维和开发层面的关键约束，包括但不限于：`uv run` 执行方式、`[[tool.uv.index]]` 阿里云镜像源配置、`pyproject.toml` 与 `skill.json` 版本同步、外部依赖、运行时约束、路径约定等。

**可酌情扩充**（规范要点必须保留，以下为补充）：
- 「需求说明」可追加"核心能力""不触发场景"小节
- 以上为可选扩充，规范中的 6 个要点和表头必须保留