# Native 澄清参考

进入 Shape 后必须读取本文件。完成问题判定、静默假设检查和共享理解确认前，不得修改项目实现或推进到 Build。

## 是否需要提问

先区分三类信息：

- **可调查事实**：仓库现状、工具能力、依赖默认值和运行环境。由 Agent 调查；可以将彼此独立的事实调查委派给 subagent。
- **用户决定**：不同选择会实质改变输出、默认行为、失败结果、范围或不可逆影响。由用户确认。
- **实现选择**：不改变用户可见结果的算法、结构和工作方式。由 Agent 决定。

只有歧义会实质改变用户可见结果，而且无法从用户要求、正式规格或项目规则中可靠确定时，才询问用户。问题应来自真实分歧；普通实现选择由 Agent 直接决定。用户直接提供文件、附件、链接或本地路径作为需求来源时，`brief.md` 是持久化澄清产物：先在 `# Scope` 下的 `## Source coverage` 呈现完整来源需求和覆盖状态，再在 `# Open questions` 提出歧义、遗漏或隐含边界问题；仅供排错、取证、审查或实现参考的材料不自动触发，用途不明时先澄清。来源文档按标题、段落、列表、表格、代码块、示例、约束、链接和边界建立单元并记录读取与覆盖状态；可执行来源单元必须同时进入完整目标 Spec 和至少一个验收 ID，背景或非目标只需保留归类和理由，不要求验收 ID；用户修正原文时将旧单元标为 `superseded` 并链接替代单元。不可访问的链接、无法解析的文件、部分读取来源或未映射的可执行来源单元保持 `[blocking]`；分块读取不减少最终覆盖集合，摘要不能替代来源覆盖映射。

把模糊行为改写为可比较的“输入 → 输出”或“触发 → 结果”。每个问题应包含：

- 问题：需要决定的用户可见差异；
- 推荐：首选项及理由；
- 影响：各选项对结果的实际影响。

## 如何向用户提问

到达用户决策点后暂停推进，等待用户明确选择。只有一个合法选项时，说明原因并直接采用；开放式问题或无法准确列出选项的问题使用文本提问。

存在两个或更多清晰、互斥且可执行的选项，并且当前平台提供 `AskUserQuestion` 时，优先使用结构化提问：

- Sequential 模式一次提交一个单选或多选问题；
- Batch 模式在一次请求中提交本轮完整的问题集合；如果工具无法容纳完整集合，整批改用文本提问，不因工具限制拆散本轮问题；
- 每个选项使用简短标签并说明实际影响；推荐项放在首位并说明理由，推荐不代替用户确认；
- 工具调用成功后直接等待用户作答，不再输出一套重复的文本选项；
- 工具不可用或调用失败时，本次会话后续问题直接使用文本方式，不反复尝试同一个工具。

使用文本提问时，明确写出“单选”或“多选”，用编号列出选项、推荐和每项影响，要求用户回复编号，然后暂停等待。

## 决策树与事实调查

在提出第一道用户问题前，先建立并持续维护一棵决策树。树中只包含会实质改变用户可见结果的用户决定；可调查事实作为决定的前置条件，普通实现选择由 Agent 自行处理。

每个决定节点至少写明：要决定什么、它依赖哪个决定、需要先调查哪些事实，以及当前处于等待、可提问还是已解决。依赖的决定和事实都已确定后，该节点才可以向用户提问。同一轮提出的问题必须彼此独立。

决策树只存在于 Agent 的工作过程，不新增 Runtime 文件或状态字段。只有实际未解决的用户问题才用现有 `[blocking]` 行写入 brief。每次用户回答或事实调查产生结论后，立即更新受影响的节点和后续分支，再重新确定当前可以提问的节点。

某项事实尚未确定时，只暂停依赖该事实的节点及其后续分支，其他互不相关的问题继续处理。当前暂时没有可提问节点时，继续调查等待中的事实并检查是否还有遗漏分支。

## Sequential模式

1. 根据决策树调查所需事实，并按上述规则隔离仍在等待事实的分支。
2. 从当前可提问节点中选择一个问题；存在多个候选时，优先询问会影响更多后续选择，或对用户可见结果影响更大的问题。
3. 在 brief 中保存一项 `- [blocking] <问题>`。
4. 一次只提出一个当前可提问节点并等待回答；下一轮再提出下一个用户决定。
5. 用户回答后立即更新 Decisions、brief 和完整目标规格。
6. 更新决策树并重新计算当前可提问节点，再开始下一轮。

模糊、部分或未回答的内容继续保持 `[blocking]`。一个答案只决定它明确覆盖的行为。

## Batch模式

每轮从决策树中找出当前可以一起提问的完整问题集合：这些问题所依赖的决定和环境事实已经确定，而且答案彼此不依赖。

1. 在 brief 中保存 `- [blocking] Q1: <问题>`、`- [blocking] Q2: <问题>`。
2. 一次提出本轮全部当前可提问节点，并分别给出问题、推荐和影响。
3. 用户回答后更新正式产物；未回答或不明确的问题继续保持 `[blocking]`。
4. 更新决策树中的已回答和未回答节点，再计算下一轮的完整节点集合。

每个独立决定保留为单独问题；同一批互不依赖的问题在一轮中一起提出。

## 持久化与最终确认

每次确认都立即写入现有 change 的 Decisions 和完整目标规格，并同步更新 brief。补充答案继续写入同一个 change。

只有所有已识别分支都已处理、没有可能改变用户可见行为的待调查事实、当前可提问节点为空，并且未明说的假设也没有产生新问题时，才开始最终确认：

1. 检查是否仍有可能影响结果但尚未明说的假设；
2. 向用户提供目标、范围、关键决定、验收标准和非目标摘要；
3. 在 brief 中保存 `- [blocking] CONFIRM: <确认内容>`；
4. 等待用户明确确认；
5. 确认后移除阻塞项并使用 `--confirmed` 推进。

用户最初提出需求不等于最终共享理解确认。用户补充或否定摘要时，更新正式产物并继续澄清。