open → build → verify → archive 四步,但仍保留 OpenSpec 状态、根因消除检查、验证和归档。
hotfix 不是”无流程”——它只是减少前期设计成本,同时保留恢复、验证和归档。

hotfix 快在前期设计成本更低,但根因、验证和归档仍然保留
怎么触发
hotfix 通常不是你手敲的命令。用户调用/comet 并进入 Classic 后,内部 /comet-classic 会在 Step 0 优先做预设检测:
你也可以直接输入
/comet-hotfix。正常恢复仍使用 /comet;配置进入 Classic 后,内部 /comet-classic 会读取 .comet.yaml 的 workflow 字段,并在 phase: build 时路由回 /comet-hotfix。
适合什么场景
适用条件(必须全部满足):- 修复已有功能的 bug,不新增 capability
- 不涉及接口变更或架构调整
- 改动范围可预估(文件数仅作提示,不是硬性升级条件)
和 full、tweak 的关系
如果你不确定用 hotfix 还是 full,先用 hotfix——命中质变信号时 Comet 会暂停让你升级,不会走错。
你会经历什么
Step 1:快速开启(预设 open)
加载openspec-new-change(不做 openspec-explore 长探索),创建精简版产物:
初始化 hotfix 状态(
init 写入的默认值见下表):
design.md(只对 full 要求),所以 open 完成后直接跳到 build,跳过 design 阶段。
hotfix 初始化的默认值
init <name> hotfix 写入 .comet.yaml 的默认值(和 tweak 完全一样,都跳过设计阶段):
hotfix 会在入口暂停一次,让你显式选择当前分支、创建分支或创建 worktree;不会静默选择隔离模式。确认后,
isolation 和 bound_branch 会记录实际执行工作区,后续意外切换分支会被阻止。其余 build 字段使用预设值,guard 对预设工作流豁免 review_mode/tdd_mode 选择检查。build_mode: direct 默认只允许 hotfix/tweak,full 必须显式设 direct_override: true。
Step 2:直接构建(预设 build)
使用默认值build_mode: direct、tdd_mode: direct、review_mode: off,并沿用入口时已确认的 isolation。跳过 brainstorming 和 writing-plans。逐任务执行:
- 读 tasks.md 未完成任务
- 每个任务:改代码 → 格式化 → 跑测试 → 勾选
- [x]→ 提交(fix: <简述修复>) - 全部完成后显式运行项目测试和构建命令
/comet-build 的计划与执行方式选择(注意:这不触发 full 升级,只切换执行方式,workflow 仍是 hotfix)。修复影响已有 spec 验收场景时,创建 delta spec(仅 ## MODIFIED Requirements)。
Step 3:根因消除检查(hotfix 专属)
这是 hotfix 独有的步骤(tweak 没有),在 build guard 之前执行,确保修复确实消除了问题根因:- 读 proposal.md 的 bug 描述和根因
- 搜索验证问题代码不再存在
- 根因未消除 → 回 Step 2 继续修复(仍在 build 阶段,无需状态回退)
Step 4:验证(预设 verify)
复用/comet-verify,由规模评估决定 light 或 full:
想增加审查可在验证前手动设置:
Step 5:归档(预设 archive)
复用/comet-archive。要求 verify_result: pass,并等待归档前最终确认。如有 delta spec,同步到 main spec。
升级判定(三层分工)
hotfix 的范围判定采用三层分工,避免”用纯文件数当硬性升级条件”误杀正常 bug 修复:1. 质变信号(命中任一即暂停)
2. 文件数 tripwire(用户拍板)
改动文件数超过提示阈值(如超过 4 个)时暂停交你决定。文件数是提示触发器,不是硬性升级条件——文件多不等于有质变。3. 验证级别(scale 脚本判定)
comet-state scale 只决定 verify_mode,不卡流程、不触发升级。
升级决策(停顿点)
命中信号或 tripwire 时,Comet 暂停让你二选一(不能自行升级或自行判定可继续):
选 B 后用合法升级通道(不能手工编辑
.comet.yaml):
workflow: full、classic_profile: full、phase 回退到 design、清空 design_doc,然后加载 /comet-design 补 Design Doc。已完成的代码、tasks 和 OpenSpec artifacts 都保留——你只补一个 Design Doc,不是从头来。preset-escalate 只能从 phase: build 的 hotfix/tweak 触发,其他情况会报错。
连续执行和必停点
hotfix 默认一次性连续执行——调用后自动推进,不主动停顿。但无论auto_transition 取何值,以下情况必须暂停等你确认:
- 命中升级判定信号
- 任务超过 3 个转入
/comet-build时的工作区和执行方式选择 - 验证阶段的验证失败决策,以及 Archive 阶段的归档与交付确认
- 归档前最终确认
auto_transition: false 时降级为逐阶段手动推进(每个 phase 边界停下,由你手动运行下一阶段命令)。
退出条件
- Bug 已修复,测试通过
- change 已归档
- 如有 spec 变更,已同步到 main spec
- 阶段守卫:build→verify 前
comet-guard <name> build --apply,verify→archive 前comet-guard <name> verify --apply
恢复
hotfix 幂等。中断后用/comet 恢复;配置进入 Classic 后,内部 /comet-classic 读取 .comet.yaml 的 workflow 字段,并在 phase: build 时路由回 /comet-hotfix。comet-state check <name> build --recover 给出恢复上下文,从 tasks.md 第一个未完成任务继续。
下一步
- tweak 预设 — 另一个轻量预设(调整行为或内容)
- 自动推进机制 — 预设的连续执行、升级和
preset-escalate - 五阶段停顿点和用户选择点 — hotfix 的停顿点
- verify 阶段 — hotfix 复用的验证流程

