comet-hotfix

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Comet 预设路径：Hotfix

Comet Preset Path: Hotfix

快速 bug fix 工作流：open → build → verify → archive。跳过 brainstorming 和完整 plan，适用于行为修复、不涉及新 capability 设计的场景。

适用条件（必须全部满足）：

修复已有功能的 bug，不新增 capability
不涉及接口变更或架构调整
改动范围可预估（通常 ≤ 2 个文件）

不适用：如修复过程发现需要架构调整，应升级为完整

/comet

流程。

Quick bug fix workflow: open → build → verify → archive. Skip brainstorming and full planning, applicable for behavior fixes and scenarios that do not involve new capability design.

Applicable Conditions (must meet all):

Fix bugs in existing features, no new capability added
No interface changes or architecture adjustments involved
Scope of changes is predictable (usually ≤ 2 files)

Not Applicable: If architecture adjustments are found necessary during the fix, upgrade to the full

/comet

process.

流程（preset workflow，4 阶段）

Workflow (preset workflow, 4 phases)

执行链路：open → build → verify → archive。Hotfix 为每个阶段提供默认决策：精简开启、直接构建、按规模验证、验证通过后归档。

开始前先定位 Comet 脚本：

bash

COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
COMET_GUARD="${COMET_GUARD:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-guard.sh' -type f -print -quit 2>/dev/null)}"
COMET_ARCHIVE="${COMET_ARCHIVE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-archive.sh' -type f -print -quit 2>/dev/null)}"

Execution chain: open → build → verify → archive. Hotfix provides default decisions for each phase: streamlined initiation, direct build, scale-based verification, and archiving after verification passes.

Locate the Comet scripts first:

bash

COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
COMET_GUARD="${COMET_GUARD:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-guard.sh' -type f -print -quit 2>/dev/null)}"
COMET_ARCHIVE="${COMET_ARCHIVE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-archive.sh' -type f -print -quit 2>/dev/null)}"

1. 快速开启（preset open）

1. Streamlined Initiation (preset open)

复用 Comet open 能力创建 change，但使用 hotfix 默认值：不执行

openspec-explore

长探索，直接进入精简 change 创建。

立即执行： 使用 Skill 工具加载

openspec-new-change

技能。禁止跳过此步骤。

技能加载后，按其指引创建精简版产物：

```
proposal.md
```
— 问题描述 + 根因分析 + 修复目标（无需方案对比）
```
design.md
```
— 修复方案（1 个即可，无需多方案对比）
```
tasks.md
```
— 修复任务清单
无需 delta spec（除非修复改变了已有 spec 的验收场景）

初始化 Comet 状态文件：

bash

bash "$COMET_STATE" init <name> hotfix

初始化后验证状态：

bash

bash "$COMET_STATE" check <name> open

阶段守卫完成 open → build 过渡：

bash

bash "$COMET_GUARD" <change-name> open --apply

Reuse Comet's open capability to create a change, but use hotfix defaults: skip the long

openspec-explore

exploration and directly proceed to streamlined change creation.

Execute immediately: Use the Skill tool to load the

openspec-new-change

skill. Skipping this step is prohibited.

After loading the skill, follow its guidance to create streamlined deliverables:

```
proposal.md
```
— Problem description + root cause analysis + repair objectives (no solution comparison needed)
```
design.md
```
— Repair solution (only 1 required, no multi-solution comparison needed)
```
tasks.md
```
— Repair task list
No delta spec required (unless the fix changes acceptance scenarios of existing specs)

Initialize the Comet state file:

bash

bash "$COMET_STATE" init <name> hotfix

Verify the state after initialization:

bash

bash "$COMET_STATE" check <name> open

Complete the open → build transition with phase guard:

bash

bash "$COMET_GUARD" <change-name> open --apply

2. 直接构建（preset build）

2. Direct Build (preset build)

使用 hotfix 默认值：

build_mode: direct

。跳过

superpowers:brainstorming

和

superpowers:writing-plans

（除非任务 > 3 个；若超过 3 个任务，转入

/comet-build

的计划与执行方式选择）。

继续或开始修改前，按

comet/reference/dirty-worktree.md

协议处理未提交改动。若归因后发现修复范围超出 hotfix，按本文件“升级条件”处理。

立即执行： 按 tasks.md 逐个执行任务：

读取
```
openspec/changes/<name>/tasks.md
```
，获取未完成任务列表
对每个未完成任务：
- 根据任务描述修改代码
- 运行项目格式化命令（如
```
mvn spotless:apply
```
  、
```
npm run format
```
  等）
- 运行相关测试确认通过
- 将 tasks.md 中对应
```
- [ ]
```
  勾选为
```
- [x]
```
- 提交代码，commit message 格式：
```
fix: <简述修复>
```
全部任务完成后，显式运行项目相关测试和构建命令

如修复影响已有 spec 验收场景：

在

openspec/changes/<name>/specs/<capability>/spec.md

创建 delta spec

仅包含
```
## MODIFIED Requirements
```
部分

Use hotfix default:

build_mode: direct

. Skip

superpowers:brainstorming

and

superpowers:writing-plans

(unless there are >3 tasks; if more than 3 tasks, switch to the plan and execution method selection of

/comet-build

Before continuing or starting modifications, handle uncommitted changes according to the

comet/reference/dirty-worktree.md

protocol. If the repair scope exceeds hotfix limits after attribution, follow the "Upgrade Conditions" in this document.

Execute immediately: Perform tasks one by one according to tasks.md:

Read
```
openspec/changes/<name>/tasks.md
```
to get the list of unfinished tasks
For each unfinished task:
- Modify code according to the task description
- Run the project formatting command (e.g.,
```
mvn spotless:apply
```
  ,
```
npm run format
```
  , etc.)
- Run relevant tests to confirm passing
- Check the corresponding
```
- [ ]
```
  to
```
- [x]
```
  in tasks.md
- Commit code with the format:
```
fix: <brief description of the fix>
```
After all tasks are completed, explicitly run relevant project tests and build commands

If the fix affects acceptance scenarios of existing specs:

Create a delta spec in

openspec/changes/<name>/specs/<capability>/spec.md

Include only the
```
## MODIFIED Requirements
```
section

3. 根因消除检查

3. Root Cause Elimination Check

在运行 build guard 之前执行，确保修复确实消除了问题根因：

读取 proposal.md 中的 bug 描述和根因
搜索验证问题代码不再存在
如根因未消除，回到 Step 2 继续修复（此时仍在 build 阶段，无需状态回退）

升级条件：

根因消除检查发现深层架构问题 → 停止 hotfix，按升级条件阻塞确认处理
修复需要额外接口变更 → 停止 hotfix，按升级条件阻塞确认处理

根因确认消除后，运行阶段守卫完成 build → verify 过渡：

bash

bash "$COMET_GUARD" <change-name> build --apply

状态文件自动更新为

phase: verify

、

verify_result: pending

，然后进入验证。

Execute before running build guard to ensure the fix truly eliminates the root cause:

Read the bug description and root cause in proposal.md
Search and verify that the problematic code no longer exists
If the root cause is not eliminated, return to Step 2 to continue the fix (still in the build phase, no need to roll back state)

Upgrade Conditions:

Deep architectural issues found during root cause elimination check → Stop hotfix, handle according to upgrade condition blocking confirmation
Additional interface changes required for the fix → Stop hotfix, handle according to upgrade condition blocking confirmation

After confirming the root cause is eliminated, run the phase guard to complete the build → verify transition:

bash

bash "$COMET_GUARD" <change-name> build --apply

The state file will be automatically updated to

phase: verify

verify_result: pending

, then enter verification.

4. 验证（preset verify）

4. Verification (preset verify)

复用

/comet-verify

，由 comet-verify 的规模评估决定轻量或完整验证。

立即执行： 使用 Skill 工具加载

comet-verify

技能。禁止跳过此步骤。

无 delta spec 的小范围 hotfix 通常满足轻量验证条件（≤ 3 tasks、≤ 2 files），comet-verify 的规模评估会选择轻量验证路径（5 项快速检查）。若 hotfix 创建了 delta spec，则根据 comet-verify 的规模评估规则进入完整验证路径。

验证通过后，按

/comet-verify

的规则将

.comet.yaml

的

verify_result

记录为

pass

，归档前不得跳过该状态。

Reuse

/comet-verify

, where comet-verify's scale assessment determines lightweight or full verification.

Execute immediately: Use the Skill tool to load the

comet-verify

skill. Skipping this step is prohibited.

Small-scale hotfixes without delta specs usually meet lightweight verification conditions (≤3 tasks, ≤2 files), and comet-verify's scale assessment will select the lightweight verification path (5 quick checks). If the hotfix creates a delta spec, enter the full verification path according to comet-verify's scale assessment rules.

After verification passes, record

verify_result: pass

.comet.yaml

according to

/comet-verify

rules; this state cannot be skipped before archiving.

4. 归档（preset archive）

4. Archiving (preset archive)

复用

/comet-archive

。归档前必须满足

.comet.yaml

中

verify_result: pass

。

立即执行： 使用 Skill 工具加载

comet-archive

技能进行归档。禁止跳过此步骤。如有 delta spec，按 comet-archive 规则同步到 main spec，并处理关联 Design Doc 与 Plan 的归档标注。

Reuse

/comet-archive

. Before archiving,

.comet.yaml

must have

verify_result: pass

Execute immediately: Use the Skill tool to load the

comet-archive

skill for archiving. Skipping this step is prohibited. If there is a delta spec, sync it to the main spec according to comet-archive rules, and handle archiving annotations for associated Design Docs and Plans.

连续执行模式

Continuous Execution Mode

<IMPORTANT> Hotfix 流程为 **一次性连续执行**。调用 `/comet-hotfix` 后，agent 在 hotfix 自有步骤间自动推进，不主动停顿。但以下情况必须暂停等待用户确认：

遇到升级条件（见"升级条件"章节）
任务超过 3 个转入
```
/comet-build
```
时的工作区隔离和执行方式选择
验证阶段（comet-verify）的验证失败决策和分支处理决策

执行顺序：快速开启 → 直接构建 → 验证 → 归档 → 完成

每个阶段完成后立即进入下一阶段。阶段内部仍必须按上文要求调用对应 Comet/OpenSpec/Superpowers skill，被调用的 skill 如有自己的用户决策点，按该 skill 规则执行。 </IMPORTANT>

<IMPORTANT> The Hotfix process is **one-time continuous execution**. After calling `/comet-hotfix`, the agent automatically advances between hotfix's own steps without actively pausing. However, pause and wait for user confirmation in the following cases:

Encountering upgrade conditions (see "Upgrade Conditions" section)
Switching to
```
/comet-build
```
when there are more than 3 tasks (workspace isolation and execution method selection)
Verification failure decisions and branch handling decisions in the verification phase (comet-verify)

Execution sequence: Streamlined Initiation → Direct Build → Verification → Archiving → Completion

Immediately proceed to the next phase after completing each phase. Corresponding Comet/OpenSpec/Superpowers skills must still be called as required within each phase; if the called skill has its own user decision points, follow that skill's rules. </IMPORTANT>

升级条件

Upgrade Conditions

满足以下任一条件时，停止 hotfix 流程，升级为完整

/comet

：

条件	说明
改动涉及 3+ 文件	超出单点修复范围
架构变更	新模块、新接口、新依赖
数据库 schema 变更	结构性调整
引入新的 public API	修复产生了新的对外接口
修复范围超出单一函数/模块	需要多处协调修改

满足升级条件时必须暂停并等待用户明确确认升级为完整

/comet

流程。不得直接进入

/comet-design

，不得自动补充 Design Doc。

用户确认升级后，必须先更新 workflow 字段再进入完整流程：

bash

bash "$COMET_STATE" set <name> workflow full

然后在当前 change 基础上补充 Design Doc：立即使用 Skill 工具加载
comet-design
skill，后续正常走完整流程。若用户不确认升级，停止 hotfix 并报告当前变更已超出 hotfix 适用范围。

Stop the hotfix process and upgrade to full

/comet

if any of the following conditions are met:

Condition	Description
Changes involve 3+ files	Exceeds single-point repair scope
Architecture changes	New modules, new interfaces, new dependencies
Database schema changes	Structural adjustments
Introducing new public API	The fix creates a new external interface
Repair scope exceeds a single function/module	Requires coordinated modifications in multiple places

When upgrade conditions are met, pause and wait for explicit user confirmation to upgrade to the full

/comet

process. Do not directly enter

/comet-design

or automatically supplement Design Docs.

After user confirms the upgrade, must update the workflow field first before entering the full process:

bash

bash "$COMET_STATE" set <name> workflow full

Then supplement the Design Doc based on the current change: Immediately use the Skill tool to load the
comet-design
skill, then proceed with the full process normally. If the user does not confirm the upgrade, stop the hotfix and report that the current change exceeds the applicable scope of hotfix.

退出条件

Exit Conditions

Bug 已修复，测试通过
change 已归档
如有 spec 变更，已同步到 main spec

阶段守卫：build → verify 前运行

bash "$COMET_GUARD" <change-name> build --apply

，verify → archive 前按

/comet-verify

规则运行

bash "$COMET_GUARD" <change-name> verify --apply

Bug has been fixed and tests passed
Change has been archived
If there are spec changes, they have been synced to the main spec

Phase Guards: Run

bash "$COMET_GUARD" <change-name> build --apply

before build → verify, and run

bash "$COMET_GUARD" <change-name> verify --apply

before verify → archive according to

/comet-verify

rules