技术澄清与规范生成
定位
技术澄清处于需求文档定稿与进入开发之间的关键衔接点。
需求澄清关注"做什么"；技术澄清关注"怎么做"和"能不能做"。
前置条件
- 当前需求
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 时，按文件系统状态判定当前段位：
| 条件 | 段位 | 动作 |
|---|---|---|
questions.md 不存在 | 技术澄清段（首次） | 执行技术澄清段 |
questions.md 有 [open] + spec.md 不存在 | 技术澄清段（重入） | 执行技术澄清段 |
questions.md 有 [open] + spec.md 存在 | specify 段（重入） | 执行 specify 段 |
questions.md 全非 open + spec.md 不存在 | specify 段（首次） | 执行 specify 段 |
questions.md 全非 open + spec.md 存在 | 质量验证 | 直接进入质量验证 |
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 职责：
- 通读 req.md，评估技术复杂度（简单/中等/复杂）
- 按复杂度选择澄清维度（参考
references/technical-clarification-guide.md） - 对照 context.md 白名单自答（追加
resolved_by_doc条目到 questions.md） - 无法自答的问题追加为
open条目到 questions.md - 所有可自答的结论写入 req.md "技术澄清"章节（格式参考
references/technical-clarification-template.md） - 读取 questions.md 已有的
answered条目（重入场景），将答复融入 req.md
跳过条件（由 subagent 在执行中自行判定）：
- 需求极简（配置变更/文案修改/简单 Bug 修复）且无技术风险
- 追加
[dropped]条目 + req.md 标注"技术审查通过" - 以
status=ok返回
回传处理：
| status | 处理 |
|---|---|
ok | 技术澄清结论已写入 req.md → 进入 specify 段 |
blocked_on_questions | questions.md 有新 [open] → pipeline 退出（blocked 卡点） |
fail | 写 last_failure → pipeline 退出 |
代问上限：技术澄清段单 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 中定义。
回传处理：
| status | 处理 |
|---|---|
ok | spec.md 已生成 → 进入质量验证 |
blocked_on_questions | questions.md 有新 [open] → pipeline 退出（blocked 卡点） |
fail | 写 last_failure → pipeline 退出 |
代问上限：specify 段单 attempt 内最多 5 round。
4. 质量验证（主编排内联）
对 spec.md 与 req.md 做覆盖性对比，并执行内容门禁：
| 检查项 | 通过标准 |
|---|---|
| 用户场景 | 至少一个主流程场景，且包含可验证的验收场景 |
| 功能需求 | 每项需求可测试、无歧义，并覆盖 req.md 的核心业务目标 |
| 成功标准 | 至少一项可量化或可观察的验证标准 |
| 边界与依赖 | 边界场景、范围、依赖与假设已记录；不适用项必须说明理由 |
| 澄清状态 | 不遗留未处理的 [NEEDS CLARIFICATION] 标记；无法确定的信息已写入 questions.md 的 open 条目 |
| 技术类型 | subagent 回传的 tech_type 为 backend / frontend / fullstack 之一 |
主编排按项目的实际 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，对外表现一致：
- pipeline 以 blocked 卡点退出
- 退出报告中展示 questions.md 中 [open] 条目数
- 调用方（runner/用户）修改 questions.md（[open] → [answered]）
- 以
action=answer再次调起 pipeline - 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 升级为回退重入。
可重入约定
- 代问重入（pipeline 内部）：round +1（attempts 不变）
- 回退重入：调用方按
state-mutation-guide.md§2 提供 retry 指令与iteration-patches/attempt-*.md；pipeline 仅在attempts < max_attempts时递增 attempts - 每次调用前：重新生成
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
