用途
complete-spec 是「逆向工程到规格驱动开发」（Reverse Engineering to Spec-Driven Development）流程中的第 5 步（共 6 步）。它的目标是通过交互式问答，解决规格文件中遗留的 [NEEDS CLARIFICATION] 标记，使规格达到可进入实现阶段的完整度。
预计耗时 30-60 分钟（交互式）。前置条件：第 4 步已完成，即 docs/gap-analysis-report.md 存在且包含澄清清单。输出：specs/ 目录下所有 [NEEDS CLARIFICATION] 标记均已解决的更新后规格。
规范路径
- 差距分析报告：docs/gap-analysis-report.md
- 功能规格文件：specs/*.md
- 澄清进度：specs/.clarification-progress.md
主要能力与使用方式
阶段 1：收集澄清项
读取 docs/gap-analysis-report.md；若文件不存在，向用户报错并停止，提示先运行第 4 步（差距分析）。使用 Glob 读取所有匹配 specs/*.md 的规格文件；若某个文件读取失败，报告文件名与错误并跳过该文件。从差距分析报告和所有规格文件中提取每一行包含 [NEEDS CLARIFICATION] 的内容，并为每个标记记录：来源文件名、功能名称（标记上方最近的标题）、标记文本、优先级标签（P0/P1/P2/P3，未标注时默认 P1）。
零标记保护：若所有文件中未发现任何 [NEEDS CLARIFICATION] 标记，告知用户「所有规格已完整，未发现澄清标记，请进入第 6 步（从规格实现）」并停止执行。
进度续跑：检查 specs/.clarification-progress.md 是否存在。若存在，读取并识别已解决的标记，从工作列表中移除，并向用户报告「发现已有进度文件，{N}/{total} 个标记已解决，从标记 {next} 继续」。
呈现摘要：按功能对剩余标记分组，排序为 P0 优先，其次 P1、P2、P3，并向用户展示分组列表，等待用户确认后再继续。
阶段 2：交互式问答
对每个未解决标记（从 P0 开始）：向用户呈现标记上下文（功能名称、问题、规格文件中的相关上下文）；一次只问一个聚焦问题，并在相关时提供常见模式或行业标准示例；等待用户回答。
若用户回答「不知道」或表示不确定，则建议常见行业模式，并提出可将其标记为延后（P3）；若用户同意延后，记录延后并进入下一个标记。若用户回答与先前记录的需求矛盾，则明确指出冲突：「这与 [文件名] 中的 [先前需求] 冲突，应以哪个为准？」等待解决后再继续。
行为约束：每条消息只问一个问题，不合并多个澄清项；在进入下一问题前，先总结对当前回答的理解；根据实际项目领域调整提问风格与术语；每解决第 5 个标记后提示「进度：{resolved}/{total} 个标记已解决」。
阶段 3：更新规格
每次用户回答后，立即更新相关规格文件，不批量更新。加载操作文件获取详细更新说明：读取 skills/complete-spec/operations/update-spec-file.md。每次写入后重新读取文件并校验：[NEEDS CLARIFICATION] 标记已移除；新内容存在且格式正确；未误删既有内容。若写入失败，向用户报错并重试一次；若重试仍失败，将预期变更记录到 specs/.clarification-progress.md 并继续下一个标记。
每次成功更新后，向 specs/.clarification-progress.md 追加完成记录，包含功能名称与标记摘要、文件路径、状态（Resolved）、解决摘要（一行）、ISO 8601 时间戳。每次更新后提示「已更新 specs/{filename}.md，标记已解决」。
阶段 4：确认优先级
所有标记解决（或延后）后，向用户呈现最终优先级分布：P0（关键）、P1（高）、P2（中）、P3（低/延后）各有多少功能，并询问是否需要调整。等待用户确认；若用户要求调整优先级，立即更新相关规格文件。
阶段 5：最终校验
读取 specs/ 下所有规格文件，扫描是否仍有 [NEEDS CLARIFICATION] 标记。若有残留：向用户报告每个残留标记及其文件与位置，询问是现在解决还是延后到 P3，并按阶段 2、阶段 3 的流程处理。若零残留：确认完成，提示「最终校验通过，零 [NEEDS CLARIFICATION] 标记残留，规格已准备好进入第 6 步（从规格实现）」，并删除 specs/.clarification-progress.md（因工作已全部完成）。
错误恢复
- docs/gap-analysis-report.md 未找到：停止，指示用户先运行第 4 步。
- 规格文件不可读：跳过该文件，报告错误，继续处理其余文件。
- 写入操作失败：重试一次；第二次仍失败则记录到进度文件并继续。
- 未发现标记：告知用户规格已完整，停止。
- 用户与先前需求矛盾：暴露冲突，等待解决。
- 会话中断：进度文件保留状态，下次调用时续跑。
适用场景与限制
适用于已通过第 4 步生成差距分析报告、且规格文件中存在待澄清标记的项目，尤其适合需要按优先级逐项澄清缺失功能、UX 细节与业务规则的规格完善工作。限制：必须存在 docs/gap-analysis-report.md，否则直接停止；依赖交互式问答，无法在无用户参与的情况下自动完成；未提供标记时不会执行任何澄清。