技术澄清与规范生成

定位

技术澄清处于需求文档定稿与进入开发之间的关键衔接点。

需求澄清关注"做什么"；技术澄清关注"怎么做"和"能不能做"。

前置条件

• 当前需求 meta.yaml.phase 为 initialized
• ${WORKDIR}/req.md 存在（由调用方注入或 pipeline 拉取）
• pipeline 主编排已按 references/context-and-meta-template.md 生成 context.md 与 meta.yaml

输入

• ${WORKDIR}/meta.yaml（读取 attempts / context_revision）
• 当前需求 ID（由 pipeline 主编排传入）
• ${WORKDIR}/context.md
• ${WORKDIR}/iteration-patches/attempt-${N}.md（若为回退重入，必读）

执行流程

本子 skill 由两段组成，通过 tech-lead 隔离执行，共享统一的 questions.md 代问循环机制。

1. 重入判定（pipeline 主编排执行）

每次进入本子 skill 时，按文件系统状态判定当前段位：

spec.md 不存在 → 还未进入 specify 段，统一按技术澄清段重入处理。

2. 技术澄清段（tech-lead）

pipeline 主编排按 ../references/subagent-prompt-template.md §2.0 Clarify 模板渲染 SUBAGENT_PROMPT，通过 Task(subagent_name="tech-lead", ...) 拉起 subagent。

渲染填充：${ID} / ${VERSION} / ${WORK_DIR} / attempts / round； 若 attempts > 1，附上 iteration-patches/attempt-${attempts}.md 摘要。

subagent 职责：

1. 通读 req.md，评估技术复杂度（简单/中等/复杂）
2. 按复杂度选择澄清维度（参考 references/technical-clarification-guide.md）
3. 对照 context.md 白名单自答（追加 resolved_by_doc 条目到 questions.md）
4. 无法自答的问题追加为 open 条目到 questions.md
5. 所有可自答的结论写入 req.md "技术澄清"章节（格式参考 references/technical-clarification-template.md）
6. 读取 questions.md 已有的 answered 条目（重入场景），将答复融入 req.md

跳过条件（由 subagent 在执行中自行判定）：

• 需求极简（配置变更/文案修改/简单 Bug 修复）且无技术风险
• 追加 [dropped] 条目 + req.md 标注"技术审查通过"
• 以 status=ok 返回

回传处理：

代问上限：技术澄清段单 attempt 内最多 3 round。

3. Specify 段（tech-lead）

pipeline 主编排按 ../references/subagent-prompt-template.md §2.1 Specify 模板渲染 SUBAGENT_PROMPT，通过 Task(subagent_name="tech-lead", ...) 拉起 subagent。

渲染填充：同技术澄清段。 若 attempts > 1，附上 iteration-patches/attempt-${attempts}.md 摘要。

subagent 内的 speckit-specify skill、代问指令（追加 questions.md open 条目 → blocked_on_questions 返回）均在 subagent-prompt-template.md §2.1 中定义。

回传处理：

代问上限：specify 段单 attempt 内最多 5 round。

4. 质量验证（主编排内联）

对 spec.md 与 req.md 做覆盖性对比，并执行内容门禁：

主编排按项目的实际 spec 模板识别对应章节，不要求固定的中英文标题。

• OK → 更新状态
• 遗漏或矛盾 → status=fail，在 issue 中列出缺失项，走回退重入（不在本 attempt 内简单重跑）

5. 更新状态

phase → tech-clarified；history 追加成功记录。 若回传 JSON 中含 tech_type 字段（值为 backend / frontend / fullstack），将其写入 meta.yaml.tech_type。

代问循环协议（统一）

无论技术澄清段还是 specify 段产生 blocked_on_questions，对外表现一致：

1. pipeline 以 blocked 卡点退出
2. 退出报告中展示 questions.md 中 [open] 条目数
3. 调用方（runner/用户）修改 questions.md（[open] → [answered]）
4. 以 action=answer 再次调起 pipeline
5. pipeline 重入，按 §1 重入判定表确定段位，继续执行

用户无需区分问题来自技术澄清还是 spec 生成。

round 计数规则

技术澄清段和 specify 段各自维护 round 计数：

• 技术澄清段 round：从 1 起记，每次代问重入 +1，上限 3
• specify 段 round：技术澄清完成后重置为 1，每次代问重入 +1，上限 5
• 区分方式：meta.yaml.specify_attempts[-1].rounds 中标注 stage: clarify | specify

超限后按 ../references/reentry-protocol.md §1.2 升级为回退重入。

可重入约定

1. 代问重入（pipeline 内部）：round +1（attempts 不变）
2. 回退重入：调用方按 state-mutation-guide.md §2 提供 retry 指令与 iteration-patches/attempt-*.md；pipeline 仅在 attempts < max_attempts 时递增 attempts
3. 每次调用前：重新生成 context.md，context_revision +1

子 skill 在执行前必须：

• 读取最新 attempt-*.md（若有），追加重入增量段（subagent-prompt-template.md §3）
• spec.md 覆盖前由 subagent 做快照 spec.md.prev-attempt${N}-round${R}

幂等性、产物保留、process.log 只追加等通用约束见 ../references/reentry-protocol.md。

信息不足回退（回退重入入口）

后续子 skill 发现 spec.md 不充分时返回 spec_insufficient， 调用方把 phase 回退至 initialized 并写 attempt-*.md，再次调起时重新执行本子 skill。

参考资料

• SUBAGENT_PROMPT（clarify 模板）：../references/subagent-prompt-template.md §2.0
• SUBAGENT_PROMPT（specify 模板 + 代问指令）：../references/subagent-prompt-template.md §2.1
• 技术澄清维度与最佳实践：references/technical-clarification-guide.md
• 技术澄清章节模板：references/technical-clarification-template.md
• 问题文件格式：../references/questions-md-template.md
• 上下文与元数据模板：../references/context-and-meta-template.md
• 可重入协议：../references/reentry-protocol.md

产出

• ${WORKDIR}/req.md — 原始需求（含技术澄清章节）
• ${WORKDIR}/questions.md — 澄清问题与答复（全历史）
• ${WORKDIR}/spec.md — 技术规范
• ${WORKDIR}/process.log — stream-json 流式日志
• ${WORKDIR}/meta.yaml — 更新后的 attempts / round / history
• 需求 phase 为 tech-clarified