clarify

用户输入

$ARGUMENTS

在继续之前，必须考虑用户输入（如果非空）。

大纲

目标：发现当前功能规格中的歧义或缺失决策点，并将澄清内容直接记录到规格文件中。

注意：此澄清工作流应在调用 bb-plan 技能之前运行并完成。如果用户明确表示跳过澄清（例如进行探索性试验），则可以继续，但必须提醒用户，下游返工风险会增加。

执行步骤：

1. 定位当前功能目录，并确认功能规格存在。解析最少的载荷字段：

   • FEATURE_DIR
   • FEATURE_SPEC
   • （可选）捕获 IMPL_PLAN、TASKS，供后续链式工作流使用。
   • 如果找不到功能目录或规格文件，则中止并指示用户先运行 bb-specify 技能，或检查功能分支环境。
   • 对于参数中的单引号，例如 "I'm Groot"，请使用转义语法：例如 'I'''m Groot'（或在可行时使用双引号："I'm Groot"）。

2. 加载当前规格文件。使用以下分类法，对歧义和覆盖范围进行结构化扫描。为每个类别标记状态：明确 / 部分明确 / 缺失。生成供排序使用的内部覆盖图（如果不提出问题，则不要输出原始覆盖图）。

   功能范围与行为：

   • 核心用户目标与成功标准
   • 明确声明的范围外事项
   • 用户角色 / 用户画像的区分

   领域与数据模型：

   • 实体、属性、关系
   • 身份与唯一性规则
   • 生命周期 / 状态转换
   • 数据量 / 规模假设

   交互与 UX 流程：

   • 关键用户旅程 / 顺序
   • 错误 / 空白 / 加载状态
   • 无障碍或本地化说明

   非功能质量属性：

   • 性能（延迟、吞吐量目标）
   • 可扩展性（水平 / 垂直、限制）
   • 可靠性与可用性（运行时间、恢复预期）
   • 可观测性（日志、指标、跟踪信号）
   • 安全与隐私（身份验证 / 授权、数据保护、威胁假设）
   • 合规 / 法规约束（如有）

   集成与外部依赖：

   • 外部服务 / API 及其故障模式
   • 数据导入 / 导出格式
   • 协议 / 版本假设

   边缘情况与故障处理：

   • 负面场景
   • 速率限制 / 节流
   • 冲突解决（例如并发编辑）

   约束与权衡：

   • 技术约束（语言、存储、托管）
   • 明确的权衡或被否决的替代方案

   术语与一致性：

   • 规范术语表
   • 避免使用的同义词 / 已弃用术语

   完成信号：

   • 验收标准的可测试性
   • 可衡量的完成定义式指标

   其他 / 占位符：

   • TODO 标记 / 未解决的决策
   • 缺乏量化的模糊形容词（如“健壮”“直观”）

   对于状态为“部分明确”或“缺失”的每个类别，提出一个候选澄清问题，除非：

   • 澄清不会实质性改变实现或验证策略
   • 相关信息更适合留到规划阶段处理（在内部注明）

3. 在内部生成一个按优先级排列的候选澄清问题队列（最多 5 个）。请勿一次性全部输出。遵循以下约束：

   • 整个会话中的问题总数不得超过 10 个。
   • 每个问题都必须可以通过以下任一方式回答：
     • 简短的多项选择（2–5 个不同且互斥的选项）；或
     • 一个词或短语（明确限制：“答案不超过 5 个词”）。
   • 只纳入答案会对架构、数据建模、任务分解、测试设计、用户体验行为、运营就绪情况或合规性验证产生实质影响的问题。
   • 确保各类别覆盖均衡：优先尝试解决影响最大的未决类别；当仍有一个高影响领域（例如安全态势）未解决时，避免提出两个低影响问题。
   • 排除已得到回答的问题、无关紧要的风格偏好，以及计划层面的执行细节（除非它们会影响正确性）。
   • 优先选择能降低后续返工风险或避免验收测试不匹配的澄清问题。
   • 如果有超过 5 个类别尚未解决，按（影响程度 × 不确定性）启发式选择优先级最高的 5 个。

4. 顺序提问流程（交互式）：

   • 每次恰好提出一个问题。

   • 对于多项选择题：

     • 分析所有选项，并根据以下因素确定最合适的选项：
       • 该项目类型的最佳实践
       • 类似实现中的常见模式
       • 降低风险（安全、性能、可维护性）
       • 与规格中明确提出的项目目标或约束相符
     • 在顶部醒目地给出你的推荐选项，并用 1–2 句话说明理由。
     • 按以下格式呈现：**推荐：** 选项 [X] - <理由>
     • 然后以 Markdown 表格列出所有选项：

     选项	描述
     A	<选项 A 的描述>
     B	<选项 B 的描述>
     C	<选项 C 的描述>（如有需要，可添加 D/E，最多 5 项）
     简答	提供其他简短答案（不超过 5 个词）（仅在适合自由回答时包含）

     • 表格后添加：你可以回复选项字母（例如 “A”）、回复 “yes” 或 “recommended” 接受推荐，或提供自己的简短答案。

   • 对于简答题（没有合适的离散选项时）：

     • 根据最佳实践和上下文提供你的建议答案。
     • 按以下格式呈现：**建议：** <你建议的答案> - <简要理由>
     • 然后输出：格式：简短答案（不超过 5 个词）。你可以回复 “yes” 或 “suggested” 接受建议，也可以提供自己的答案。

   • 用户回答后：

     • 如果用户回复 “yes”、“recommended” 或 “suggested”，则使用你先前给出的推荐或建议作为答案。
     • 否则，验证答案是否对应某个选项或符合不超过 5 个词的限制。
     • 如果答案含糊不清，提出一个简短的澄清问题（仍计为同一个问题；不要进入下一个问题）。
     • 确认答案有效后，将其记录在工作记忆中（暂不写入磁盘），然后进入队列中的下一个问题。

   • 出现以下情况时停止提问：

     • 所有关键歧义都已提前解决（剩余队列中的问题不再必要）；或
     • 用户表示结束（“done”、“good” 或 “no more”）；或
     • 已提出 5 个问题。

   • 不得提前透露队列中尚未提出的问题。

   • 如果一开始没有符合条件的问题，立即说明没有关键歧义。

5. 每次接受答案后立即集成（增量更新方式）：

   • 在内存中维护规范表示（在开始时加载一次）以及原始文件内容。
   • 本次会话中集成第一个答案时：
     • 确保存在 ## Clarifications 部分（如果缺失，则根据规范模板将其创建在最高层级的上下文／概览部分之后）。
     • 在该部分下创建（如果尚不存在）一个 ### Session YYYY-MM-DD 子标题，日期为今天。
   • 接受答案后立即追加一条项目符号：- Q: <question> -> A: <final answer>。
   • 随即将澄清内容应用到最合适的部分：
     • 功能歧义 -> 在功能需求中更新或添加项目符号。
     • 用户交互／参与者区分 -> 在用户故事或参与者子部分（如果存在）中更新已澄清的角色、约束或场景。
     • 数据结构／实体 -> 更新数据模型（添加字段、类型、关系），并保持原有顺序；简要注明新增约束。
     • 非功能约束 -> 在非功能／质量属性部分添加或修改可衡量的标准（将模糊形容词转化为指标或明确目标）。
     • 边缘情况／异常流程 -> 在边缘情况／错误处理下添加新项目（或在模板提供占位符时创建相应子部分）。
     • 术语冲突 -> 在规范中统一术语；仅在必要时保留原术语，并添加一次 (formerly referred to as "X")。
   • 如果澄清内容使先前的模糊陈述失效，请替换该陈述，而不要重复添加；不得留下过时且相互矛盾的文本。
   • 每次集成后立即保存规范文件，以最大限度降低上下文丢失风险（原子覆盖）。
   • 保持格式：不要重排无关部分；保留标题层级。
   • 每项新增澄清都应简洁且可测试（避免叙述偏离）。

6. 验证（每次写入后及最终检查时执行）：

   • Clarifications 会话中每个已接受答案恰好对应一条项目符号（不得重复）。
   • 已提问并获得回答的问题总数 <= 5。
   • 更新后的部分不再包含本次答案旨在解决的模糊占位符。
   • 不得残留相互矛盾的早期陈述（检查并移除现已无效的备选项）。
   • Markdown 结构有效；仅允许新增以下标题：## Clarifications、### Session YYYY-MM-DD。
   • 术语一致性：所有已更新部分均使用相同的规范术语。

7. 将更新后的规范写回 FEATURE_SPEC。

8. 报告完成情况（提问环节结束或提前终止后）：

   • 已提问并获得回答的问题数量。
   • 更新后的规范路径。
   • 涉及的部分（列出名称）。
   • 覆盖情况摘要表，列出每个分类及其状态：Resolved（原为部分明确／缺失，现已处理）、Deferred（超出提问配额或更适合在规划阶段处理）、Clear（已有充分说明）、Outstanding（影响较低，但仍为部分明确／缺失）。
   • 如果仍有 Outstanding 或 Deferred 项，建议继续执行 bb-plan 技能，或稍后在计划完成后再次运行 bb-clarify 技能。
   • 建议的下一步。

行为规则：

• 如果没有发现有意义的歧义（或所有潜在问题的影响都很小），请回复：“未发现值得正式澄清的关键歧义。”并建议继续推进。
• 如果缺少规范文件，请指示用户先运行 bb-specify 技能（不要在此处创建新规范）。
• 提出的问题总数不得超过 5 个（针对同一个问题的澄清重试不计为新问题）。
• 除非缺少相关信息会妨碍功能需求的明确性，否则避免询问推测性的技术栈问题。
• 尊重用户提前终止的信号（“stop”“done”“proceed”）。
• 如果因覆盖完整而未提出问题，请输出简洁的覆盖情况摘要（所有类别均为“明确”），然后建议继续推进。
• 如果达到问题限额时仍有尚未解决的高影响类别，请在“暂缓事项”下明确指出，并说明理由。

优先级上下文：{ARGS}