SKILL.md 9.42 KB

Edit Raw Blame History



name: downstream-gen
description: A5 下游文档生成——基于 docs/01 和 docs/03 推导，一次性生成 docs/02 + docs/05 + docs/06 § 三 + docs/10，回填 REQ 卡片依赖接口，把模块清单追加到 docs/08 § 二。
user-invocable: false


allowed-tools: Read Write Edit Glob Grep Skill AskUserQuestion

所有输出必须使用中文。


downstream-gen


执行步骤


A. docs/02 — 开发计划（含 REQ 级开发顺序清单）

清单颗粒度：一行一个 REQ，同一模块的 REQ 必须连续排列。


构建模块依赖 DAG。
对每个模块内部构建 REQ 间依赖，得到模块内 REQ 顺序。
合成 req_order[]：按 module_topo_order[] 依次铺开每个模块内的 REQ 序列（同模块 REQ 连续）。

环依赖打破：


模块级：若模块 DAG 存在环（module_A ↔ module_B），按启发式（字母序 / 被依赖次数多者先）破环排出 module_topo_order，并在参与环的模块里第一个 REQ 的 note 字段填入原因（如 "A↔B 互依赖：先做 A 的骨架"）。

REQ 级（同模块内）：若模块内 REQ 互依赖，同样破环，note 填原因。
非环 REQ note 留 —。


为 req_order[] 每项生成字段：


index：行号（从 1 开始）

req_id：如 REQ-SYS-001


module_id：该 REQ 所属模块，如 module_sys


rationale（选中理由）：依赖驱动的简短描述，如 所属模块无依赖，基础模块 / 依赖 REQ-SYS-001 已在前 / 所属模块依赖 module_sys 已在前


note（备注）：默认 —；仅环依赖打破场景填原因


读取并填充 ${CLAUDE_SKILL_DIR}/templates/docs-02-template.md。
写入 docs/02-开发计划.md。


完成后，用 Edit 在 docs/08-模块任务管理.md 中勾选：


- [ ] docs/02 开发计划已生成


B. docs/05 — API 接口契约


读取 ${CLAUDE_SKILL_DIR}/templates/docs-05-header-template.md，写入 docs/05-API接口契约.md 头部。
对所有模块的每个 REQ：读取并推断 ${CLAUDE_SKILL_DIR}/templates/docs-05-endpoint-template.md，追加到 docs/05。


完成后，用 Edit 在 docs/08-模块任务管理.md 中勾选：


- [ ] docs/05 API 契约已生成


B2. 回填模块头 + REQ 卡片的 TBD(A5) 字段


在docs/01-需求清单/*/_module.md（模块头）和 docs/01-需求清单/*/REQ-*.md（REQ 卡片）中搜索并回填 TBD(A5 自动补) 
打印回填统计：A5 回填 <M> 处模块"依赖模块" + <N> 处 REQ"依赖接口"。


完成后，用 Edit 在 docs/08-模块任务管理.md 中勾选：


- [ ] REQ 卡片依赖接口已回填


C. docs/06 — 页面清单

对每个有前端页面的模块：读取并填充 ${CLAUDE_SKILL_DIR}/templates/docs-06-module-pagelist-template.md，追加到 docs/06-UI交互规范.md § 三。

完成后，用 Edit 在 docs/08-模块任务管理.md 中勾选：


- [ ] docs/06 § 三 页面清单已填入


D. docs/08 — 追加模块清单

读 ${CLAUDE_SKILL_DIR}/templates/docs-08-module-row-template.md，按 module_id 字母序为每个模块渲染 bullet（模块元数据 + REQ 子项清单，REQ 序保持步骤 A 模块内顺序），追加到 docs/08。

完成后，用 Edit 在 docs/08-模块任务管理.md 中勾选：


- [ ] 下方模块列表已填入


E. docs/10 — 验收清单（项目级 SOP）

用 Read 读取 ${CLAUDE_SKILL_DIR}/templates/docs-10-header-template.md，用 Write 原样写到 docs/10-验收检查清单.md（跨平台，不用 cp）。

完成后，用 Edit 在 docs/08-模块任务管理.md 中勾选：


- [ ] docs/10 验收清单已生成


F. 验证 + 勾选 docs/08 进度 + 结束 Plan


一致性检查 + 自主修复循环（最多 3 轮，docs/01 是 REQ SSoT 不动）：


检查项：


每个 docs/01 REQ 都出现在 docs/05（作为接口，如适用）

docs/02 § 二 的 module_id 集合 = docs/08 § 二 的 module_id 集合


不一致 → 按差异类型自主修复：


REQ 缺 docs/05 endpoint → 按步骤 B 规则为该 REQ 推测，并追加到 docs/05

module_id 缺 docs/08 § 二 → 按步骤 D 规则渲染该模块 bullet（含 REQ 子项），按 module_id 字母序插入正确位置

module_id 缺 docs/02 § 二 → 重算该模块的 req_order 段（步骤 A 子流程），按拓扑序插入 docs/02 § 二


修复后重跑检查；通过 → 进入 2；3 轮仍失败 → 停下，打印最终残留差异 + 已尝试的 3 轮修复摘要让用户介入。


最终占位符扫描 + 结构性残留检查（覆盖 Plan 阶段全部产出）：


a. TBD → 自动补齐：Grep 搜索 TBD(A3 自动补) 和 TBD(A5 自动补)。有命中则就地补填（A3 残留 → 查 docs/03 填 依赖表；A5 残留 → 查 docs/05 按 REQ-ID 填 依赖接口），再 Grep 确认 0 命中；仍残留报错停下。

b. 结构性残留检查（不只看字面占位符，校验 SSoT 完整性）：
  - **docs/05 每个端点都有请求/响应 schema**：逐个解析 docs/05 的每个 endpoint 段（以 `### REQ-` 开头的小节）。每段必须同时含非空的 `- **请求**:` 与 `- **响应**:` 行——值不得为空、`TBD`、`—` 或 `【人工填写：…】`。缺失/留空 → 按步骤 B 规则就地为该端点推测补全请求/响应 schema，再复核；3 轮仍补不全则计入残留清单（见下方 c），交由 QA 循环让用户介入。
  - **docs/02 DAG 覆盖每个 REQ**：收集 docs/01 全部 REQ-ID 集合，与 `docs/02 § 二、开发顺序清单` 表中出现的 `req_id` 集合比对。任一 docs/01 REQ 未出现在 docs/02 顺序清单 → 按步骤 A 子流程把该 REQ 插入其所属模块段的正确拓扑位置（保持同模块 REQ 连续），再复核；3 轮仍无法补齐则计入残留清单交由 QA 循环。


c. 【人工填写：...】 + 结构性残留 → QA 循环等用户补：
  循环执行直到（搜索不到 `【人工填写：`）**且**（步骤 b 两项结构检查均通过）且用户选「继续」：
  - 0 残留 → 直接放行进入步骤 3
  - 有残留 → 打印残留清单（含字面占位符 `<文件:行号> — <内容摘要>`，以及结构性缺口 `docs/05 端点 <REQ-ID> 缺请求/响应 schema` / `docs/02 顺序清单缺 REQ <REQ-ID>`），用 `AskUserQuestion` 弹「继续」/「有疑问想先沟通」二选一；用户回答后重扫 + 重跑结构检查再决定放行 / 继续循环

  **每次弹 QA 前都重扫一次**（含两项结构检查）——保证用户看到的 N 是最新的，避免「用户以为填完但实际还有残留」直接放行。


docs/05 + docs/02 人工评审闸（强制，未确认不得勾选 A5）：


向用户摘要展示两份 SSoT 的关键内容，请其确认无误：


docs/05 API 契约：列出全部端点（METHOD PATH — REQ-ID），并标注任何「由 A5 自动推断」的端点/字段供重点核对。

docs/02 构建顺序：展示 req_order[] 顺序，特别标出所有 note ≠ — 的环依赖打破项（启发式选定的顺序 + 原因），供用户判断该顺序是否可接受。


用 AskUserQuestion 同时问两项确认（多问题表单），每项二选一：


「docs/05 端点/字段确认无误」：确认 / 需要修改

「docs/02 构建顺序可接受（含 cycle-breaking 选定的顺序）」：确认 / 需要修改


裁决：


两项均 确认 → 进入步骤 4 勾选 A5。
任一为 需要修改 → 用 AskUserQuestion 收集具体修改点，就地修订对应文档（docs/05 端点/字段或 docs/02 顺序/备注），改完重新展示摘要并重跑本评审闸，直到两项均 确认。未两项确认前禁止勾选 A5、禁止打印终止横幅。


完成后，用 Edit 在 docs/08-模块任务管理.md 勾选 A5 父项：


- [ ] A5 下游文档生成 — downstream-gen


打印 A5 完成横幅并停下（A6 仍未跑——A5 之后由 plan-start 派发 A6 frontend-scope-lock，A6 完成后再由 plan-start 跑 5 项终结闸；只有终结闸全过才会提示运行 coding-start）：

   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    [downstream-gen] ✅ A5 下游文档生成完成（A0~A5）

    docs/02 / docs/05 / docs/06 § 三 / docs/08 § 二 / docs/10 已就绪；
    docs/05 + docs/02 评审闸已通过；docs/08 § 一 A0~A5 已全勾。

    ⏭️ 下一步：运行 /erp-workflow:plan-start
       plan-start 会派发到 A6 frontend-scope-lock 锁定前端 scope，
       A6 完成后再由 plan-start 跑 5 项终结闸校验；
       全过才会提示运行 /erp-workflow:coding-start 进入 B 阶段。
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


参考


${CLAUDE_SKILL_DIR}/templates/docs-02-template.md
${CLAUDE_SKILL_DIR}/templates/docs-05-header-template.md
${CLAUDE_SKILL_DIR}/templates/docs-05-endpoint-template.md

${CLAUDE_SKILL_DIR}/templates/docs-06-module-pagelist-template.md（追加到 docs/06 § 三）

${CLAUDE_SKILL_DIR}/templates/docs-08-module-row-template.md（模块 bullet 行模板）
${CLAUDE_SKILL_DIR}/templates/docs-10-header-template.md