> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comet.rpamis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 五阶段停顿点和用户选择点

> 完整列出 /comet 五阶段工作流中所有需要用户做决策的停顿点——每个停顿点在哪、选什么、选完后发生什么。

Comet 会自动推进无歧义的阶段，但不会替你做产品或风险决策。每个需要你介入的地方都是一个**停顿点（blocking decision point）**——Comet 暂停并等待你选择，选择前不会继续。

本页完整列出五阶段的所有停顿点，方便你在使用前知道哪些地方需要参与。

## 你会看到什么样的提问

在支持结构化提问的平台上，例如 Claude Code，Comet 会优先把停顿点展示成可点击的单选或多选问题。你会看到每个选项的短标签和影响说明；推荐项只帮助你判断，不会替你自动选择。

| 场景                    | 你看到的体验                             | Comet 如何继续                       |
| --------------------- | ---------------------------------- | -------------------------------- |
| 单选停顿点                 | 一个单选问题，例如是否继续执行、选择哪种分支处理方式         | 你选中一项后，Comet 才写入状态或执行对应分支        |
| 多选停顿点                 | 一个多选问题，例如一次性选择隔离方式、执行方式、TDD 和审查模式  | 你提交选择后，Comet 一次性记录这些 workflow 字段 |
| 平台没有结构化提问，或第一次结构化提问失败 | 编号文本选项，明确写出“单选”或“多选”、每项影响，并要求你回复编号 | 本会话后续停顿点直接使用编号文本，不会反复尝试失败的结构化 UI |

<Note>
  如果你在某个平台上只看到编号列表，这不是流程降级。它只是输入界面从可点击选项退回文本编号；阻塞规则、选项含义和状态写入门禁都保持一致。
</Note>

## 停顿点总览

下面按阶段顺序列出所有停顿点。每个阶段的停顿点按发生先后排列，前一阶段的最后一个停顿点通过后才会进入下一阶段。

<Note>
  0.4.0-beta.5 起，Comet 只在<strong>真正的用户决策点</strong>暂停。前 3
  次可修复的验证失败、单一安全的下一步、遵循已持久化配置的操作都会自动处理，不再逐次询问。
  <code>auto\_transition: false</code> 产生的 <code>NEXT: manual</code> 只是交还控制权，
  <strong>不是用户决策点</strong>，不会问"是否继续"。
</Note>

### 路由阶段

| 顺序 | 停顿点           | 你决定什么                                    |
| -- | ------------- | ---------------------------------------- |
| 1  | workflow 目标选择 | 多个 active change 时继续哪个、新建还是继续、批次拆分后先做哪一项 |

### open 阶段

| 顺序 | 停顿点                      | 你决定什么                |
| -- | ------------------------ | -------------------- |
| 2  | PRD 拆分预检                 | 大需求是否拆成多个 change     |
| 3  | proposal/design/tasks 审视 | 最终确认名称、范围和三个文档是否符合预期 |

### design 阶段

| 顺序 | 停顿点    | 你决定什么                   |
| -- | ------ | ----------------------- |
| 4  | 设计方案确认 | brainstorming 的技术方案是否采用 |

### build 阶段

| 顺序 | 停顿点        | 你决定什么                                                        |
| -- | ---------- | ------------------------------------------------------------ |
| 5  | build 联合决策 | plan-ready 暂停或一次性选定全部工作模式（隔离 + 执行 + TDD + 审查，选 branch 时含分支名） |
| 6  | spec 漂移拆分  | 新任务超 50% 时是否拆分新 change                                       |

### verify 阶段

| 顺序 | 停顿点    | 你决定什么                                             |
| -- | ------ | ------------------------------------------------- |
| 7  | 验证例外决策 | 接受 WARNING/SUGGESTION 偏差、spec 漂移处理、或第 4 次失败后的策略选择 |

### archive 阶段

| 顺序 | 停顿点       | 你决定什么                               |
| -- | --------- | ----------------------------------- |
| 8  | 归档与交付最终确认 | 归档并立即推送 / 归档、推送并创建 PR / 回去调整 / 暂不归档 |

### 升级信号（仅 hotfix/tweak）

| 顺序 | 停顿点  | 你决定什么                             |
| -- | ---- | --------------------------------- |
| 9  | 升级评估 | 命中定性变更信号时，继续预设还是升级到 full workflow |

<p align="center">
  <img src="https://mintcdn.com/comet-bb5f5294/piE9AoWsM20071ec/assets/decision-points-illustrations/01-decision-signposts.png?fit=max&auto=format&n=piE9AoWsM20071ec&q=85&s=67ba3848bb5b65e564375a6f8e7982f2" alt="小鱼在五阶段路径上的停顿点路牌前等待用户确认" width="800" data-path="assets/decision-points-illustrations/01-decision-signposts.png" />
</p>

<p align="center">自动推进只处理无歧义衔接，遇到停顿点必须等你确认后再继续</p>

## 路由阶段停顿点

### 1 — workflow 目标选择

| 属性 | 说明                                          |
| -- | ------------------------------------------- |
| 触发 | 存在多个 active change、新建与继续并存、或 PRD 批次拆分后选择起始项 |
| 决策 | 继续哪个已有 change、是否新建、批次中先做哪一项                 |
| 展示 | active change 列表、批次清单的待开始项                  |

Comet 只在存在真正歧义时才暂停；只有一个明确相关的 active change 时会直接建议恢复。

## open 阶段停顿点

### 2 — PRD 拆分预检

| 属性 | 说明                          |
| -- | --------------------------- |
| 触发 | 输入是大型 PRD/路线图，或澄清摘要包含多个独立能力 |
| 决策 | 是否拆分为多个 change              |
| 展示 | 候选拆分清单（名称、目标、范围、依赖、验收场景）    |

选项：

| 选项                    | 结果                                                                    |
| --------------------- | --------------------------------------------------------------------- |
| 创建多个 OpenSpec changes | 每个拆分项用独立 `/comet-open` 创建，并把拆分清单持久化到 `.comet/batches/<batch-id>.json` |
| 保持为一个 change          | 继续单 change，记录不拆分原因                                                    |
| 调整拆分方案                | 重新输出候选清单并再次确认                                                         |

确认前不创建任何 artifact。每个拆分项完成后会通过 `openspec status --json` 和 `comet state check` 双重校验，全部通过才宣布拆分完成。详见[大型 PRD 拆分](/zh/guides/prd-splitting)。

### 3 — proposal/design/tasks 审视（含名称和范围）

| 属性 | 说明                                                                 |
| -- | ------------------------------------------------------------------ |
| 触发 | proposal/design/tasks 创建完成且完整性检查通过                                 |
| 决策 | 确认 change 名称、范围和三个文档是否符合预期                                         |
| 展示 | proposal（背景/目标/范围）、design（架构/选型）、tasks（数量/关键任务）、推导的 kebab-case 英文名 |

| 选项        | 结果          |
| --------- | ----------- |
| 确认，继续下一阶段 | 执行 guard 流转 |
| 需要调整      | 修改后重新请求确认   |

<Note>
  0.4.0-beta.5 起，open 阶段的需求澄清和命名默认<strong>非阻塞</strong>
  。范围和命名都明确时直接继续，不再单独暂停让你确认摘要或名称；最终审视会一次性确认名称、范围和三个文档。只有当仍存在会改变范围或目标
  change 身份的互斥选择时，才会用一次联合提问。明确请求（clear request）会跳过产物前的命名确认。
</Note>

## design 阶段停顿点

### 5 — 设计方案确认

| 属性 | 说明                                    |
| -- | ------------------------------------- |
| 触发 | brainstorming 产出设计方案后，创建 Design Doc 前 |
| 决策 | 确认技术方案                                |
| 展示 | 采用的技术方案、关键权衡和风险、测试策略、Spec Patch（如有）   |

| 选项   | 结果                          |
| ---- | --------------------------- |
| 确认   | 进入 Step 1d 定稿，创建 Design Doc |
| 需要调整 | 继续 brainstorming 迭代直到确认     |

确认前不创建 Design Doc、不写 `design_doc`、不跑 guard。

<Note>
  Step 1e
  主动式上下文压缩时，如果平台不支持程序化触发，也会暂停让你手动压缩。这不算产品决策点，但需要你确认压缩完成。
</Note>

## build 阶段停顿点

### 5 — build 联合决策

一次性联合决定 plan-ready 和全部工作模式：

| 属性 | 说明                                                   |
| -- | ---------------------------------------------------- |
| 触发 | 实施计划写入文件后                                            |
| 决策 | 立即继续还是暂停切换模型，以及隔离方式、执行方式、TDD 模式、审查模式（选 branch 时含分支名） |
| 展示 | 计划已生成的提示、各项推荐值                                       |

#### plan-ready 选择

| 选项       | 结果                                            |
| -------- | --------------------------------------------- |
| A：继续执行   | 设 `build_pause: null`，立即进入执行                  |
| B：暂停切换模型 | 设 `build_pause: plan-ready`，停止，稍后 `/comet` 恢复 |

comet 考虑了用户真实的使用场景，**允许用户用高级模型做规划，用低级模型做执行**，支持切换模型后跨设备 0 上下文恢复执行。

#### 隔离方式

| 选项       | 说明                         |
| -------- | -------------------------- |
| branch   | 当前仓库创建分支                   |
| worktree | 独立工作区，可并行开发                |
| current  | 如实记录当前工作区（hotfix/tweak 默认） |

#### 执行方式

| 选项                          | 说明                                                           |
| --------------------------- | ------------------------------------------------------------ |
| subagent-driven-development | 后台子代理实现，双阶段审查                                                |
| executing-plans             | 轻量执行                                                         |
| direct                      | 直接实现（仅 hotfix/tweak；full workflow 需 `direct_override: true`） |

#### TDD 模式

| 选项     | 说明                                  |
| ------ | ----------------------------------- |
| tdd    | 先写失败测试                              |
| direct | 不做 Red-Green-Refactor，但仍要求相关测试和回归证据 |

#### 审查模式

| 选项                        | 说明                                  |
| ------------------------- | ----------------------------------- |
| off / standard / thorough | 见[代码审查机制](/zh/concepts/review-mode) |

#### 分支名

选择 branch 隔离时，让你确认或覆盖推荐的分支名：

* full → `feature/YYYYMMDD/<name>`
* hotfix → `hotfix/YYYYMMDD/<name>`
* tweak → `tweak/YYYYMMDD/<name>`

  0.4.0-beta.5 把 plan-ready 和工作模式合并为**一次联合决策**，避免分两次暂停。推荐规则仅供参考，不能替代你的确认。

### 6 — spec 漂移拆分决策

执行中发现新任务超过初始 tasks.md 的 50% 时，强制让你选择：

| 选项           | 结果                              |
| ------------ | ------------------------------- |
| 拆分为新 change  | 通过 `/comet-open` 开新 change      |
| 继续在当前 change | 记录范围扩展，更新 tasks.md 和 delta spec |

## verify 阶段停顿点

### 7 — 验证例外决策

| 属性 | 说明                                                   |
| -- | ---------------------------------------------------- |
| 触发 | light 6 项或 full 7 项检查未通过，且属于需要用户判断的情形                |
| 决策 | 接受偏差、处理 spec 漂移、或第 4 次失败后的策略选择                       |
| 展示 | 失败项、严重级别（CRITICAL/IMPORTANT/WARNING/SUGGESTION）、推荐处理 |

0.4.0-beta.5 起验证失败按以下规则分类处理：

| 情形                                 | 处理                                     |
| ---------------------------------- | -------------------------------------- |
| CRITICAL/IMPORTANT 或客观可修复问题        | 自动 `verify-fail` 回 build 修复（重试上限内），不问你 |
| WARNING/SUGGESTION 且修复引入行为/范围/风险权衡 | 暂停让你选修复或接受，接受时记录原因和影响范围                |
| WARNING/SUGGESTION 且修复安全、无权衡       | 自动修复，不暂停                               |
| 连续 3 次失败后的第 4 次                    | 暂停，只提供"继续修复"或"停止并寻求外部决策"两个选项           |

CRITICAL 和 IMPORTANT 发现**永不可豁免**。只有接受 WARNING/SUGGESTION 偏差或第 4 次失败后的策略选择才需要你介入。连续失败计数由 machine-owned 的 `verify_failures` 字段持久化，跨恢复保留。

### spec 漂移处理（仅 full 检查 6，属于停顿点 7 的一种触发）

delta spec 与 Design Doc 矛盾时三选一：

| 选项 | 结果                                                                  |
| -- | ------------------------------------------------------------------- |
| A  | 在 Design Doc 追加"Implementation Divergence"说明                        |
| B  | `transition verify-fail` → `/comet-build` → 加载 `brainstorming` 重新对齐 |
| C  | 接受偏差，归档时 Design Doc 标记 `superseded-by-main-spec`                    |

## archive 阶段停顿点

### 8 — 归档与交付最终确认

| 属性 | 说明                                                   |
| -- | ---------------------------------------------------- |
| 触发 | 入口状态验证通过后，执行归档脚本前                                    |
| 决策 | 是否立即归档，以及完整归档提交是只推送还是推送并创建 PR                        |
| 展示 | change 名、验证报告、当前绑定分支、工作区和已有未提交改动的归属摘要、不可逆归档动作及所选远端交付 |

| 选项              | 结果                                                                                     |
| --------------- | -------------------------------------------------------------------------------------- |
| 确认归档并立即推送       | 执行归档，将 `handled` 包含在唯一归档提交中，然后推送一次                                                     |
| 确认归档、立即推送并创建 PR | 执行归档，推送唯一归档提交，然后创建 PR                                                                  |
| 需要调整或重新验证       | `archive-reopen` 回 `phase: verify` → `/comet-verify`                                   |
| 暂不归档            | 不写 `archive_confirmation`，保持 active change、`phase: archive` 和 `branch_status: pending` |

<Note>
  <code>branch\_status: handled</code> 表示交付方式已经确认，不表示 push 或 PR 已经成功。Comet
  在归档完成后、唯一归档提交前写入它；只有选定的远端操作成功后才清除 current selection
  并宣告完成。归档阶段不再加载 <code>finishing-a-development-branch</code>。
</Note>

<Note>
  无论 <code>auto\_transition</code> 是 auto 还是 manual，归档前都会执行停顿点
  8。验证通过不会自动归档。
</Note>

## 升级信号停顿点（仅 hotfix/tweak）

### 9 — 升级评估

| 属性 | 说明                                               |
| -- | ------------------------------------------------ |
| 触发 | hotfix/tweak 命中定性变更信号（跨模块、新 API、schema 变更、深层架构等） |
| 决策 | 继续预设轻量流程还是升级到 full workflow                      |
| 展示 | 命中的信号和升级后的影响                                     |

| 选项       | 结果                                                           |
| -------- | ------------------------------------------------------------ |
| 继续预设流程   | 确认范围可控，继续 hotfix/tweak                                       |
| 升级到 full | `comet state transition <name> preset-escalate` 合法回退到 design |

## 停顿点规则

所有停顿点遵循 `comet/reference/decision-point.md` 协议。0.4.0-beta.5 起协议先判断是否真的需要用户输入：

* **用户决策**——两个或更多有效选项会改变范围、行为、可接受风险或不可逆结果，必须你选。
* **自动处理**——请求内只剩一个安全的下一步（修复客观失败、调和可验证状态、重试幂等检查、遵循已持久化配置），直接执行并报告，不制造确认。
* **停止条件**——缺少依赖、状态损坏、路径逃逸或外部命令不可用，没有有效下一步，报告阻塞和恢复条件。
* **手动交接**——`NEXT: manual` 只交还控制权，不是新的用户决策点；打印 HINT 并结束当前调用，不问"是否继续"。

只有第一类用本协议的阻塞规则。能合并回答的相邻选择合并提问，不再重复问仍有效的已持久化选择。展示选项前先预检平台能力和状态，只显示可执行的选项；某字段只有一个合法值时直接说明并应用，不单独暂停。

* **必须暂停**——不能基于推荐、默认值或当前状态自动选择。
* **优先用结构化提问**——平台支持时展示可点击的单选/多选；不可用时降级为编号文本选项。
* **降级只判定一次**——如果第一次结构化提问失败，本会话后续停顿点直接用文本选项。
* **选择前不推进**——不创建产物、不跑 guard、不流转。
* **推荐仅供参考**——推荐规则不能替代你的确认。

## 下一步

* [open 阶段](/zh/phases/open) — open 的停顿点
* [build 阶段](/zh/phases/build) — build 的联合决策
* [verify 阶段](/zh/phases/verify) — verify 的验证例外决策
* [archive 阶段](/zh/phases/archive) — archive 的归档与远端交付确认
* [工作流概念](/zh/concepts/workflow) — 用户参与的阻塞点总览