hotfix

热修复

仅限显式调用：只有用户通过 /hotfix 明确请求时，才能运行此技能。不要根据上下文匹配自动调用。

阶段 1：评估严重程度

阅读错误描述或 ID。根据 /bug-triage 的等级评估严重程度：

• S1（严重）：崩溃、数据丢失或功能完全失效——游戏无法继续（安全问题按其影响程度评级）
• S2（高）：主要功能损坏，但游戏仍可玩
• S3 或更低：功能受损但有替代方案，或仅为外观问题——按常规错误修复工作流处理

使用 AskUserQuestion 确认：

• 提示：“我评估此问题的严重程度为 [assessed severity]——[brief rationale]。请确认严重程度以继续：”
• 选项：
  • [A] S1（严重）——崩溃、数据丢失或功能完全失效
  • [B] S2（高）——主要功能损坏，但游戏仍可玩
  • [C] S3 或更低——转至常规错误修复工作流

如果选择 [C]：停止。结论：已转交——S3 及以下问题请使用常规错误修复工作流。

---

阶段 2：创建热修复记录

起草热修复记录：

## Hotfix: [Short Description]
Date: [Date]
Severity: [S1/S2]
Reporter: [Who found it]
Status: IN PROGRESS

### Problem
[Clear description of what is broken and the player impact]

### Root Cause
[To be filled during investigation]

### Fix
[To be filled during implementation]

### Testing
[What was tested and how]

### Approvals
- [ ] Fix reviewed by lead-programmer
- [ ] Regression test passed (qa-tester)
- [ ] Release approved (producer)

### Rollback Plan
[How to revert if the fix causes new issues]

询问：“我可以将其写入 production/hotfixes/hotfix-[date]-[short-name].md 吗？”

如果可以，则写入文件；如有需要，先创建目录。

---

阶段 3：创建热修复分支

检查这是否为 git 仓库：

Bash: git rev-parse --is-inside-work-tree 2>/dev/null

如果此命令失败或返回空值：注明“不是 git 仓库——请手动创建分支。”并跳过分支创建。

[base-ref] 是此错误所在的发行版本。发行版本是 main（主干）上的标签，因此应使用该发行版本的标签（git tag --list；最新的通常是线上版本）——或者，如果曾创建 release/* 分支来稳定该发行版本，则使用该分支（git branch --list 'release/*'）。切勿使用 main 的最新提交：其中可能包含尚未发布的工作。

如果检查通过，则在创建分支前使用 AskUserQuestion：

• 提示：“准备从 [base-ref] 创建热修复分支 'hotfix/[short-name]'，是否继续？”
• 选项：
  • [A] 是——创建分支
  • [B] 使用其他基础引用——我来指定
  • [C] 跳过——我会自行创建分支

只有用户选择 [A] 时，才运行 git checkout -b hotfix/[short-name] [base-ref]。如果选择 [B]：询问用户基础引用，然后使用该引用运行命令。如果选择 [C]：跳过分支创建并继续阶段 4。

---

阶段 4：调查并提出方案

找出根本原因。起草最小修复方案：要更改哪些文件、更改的作用，以及明确不处理哪些内容。不要在热修复中顺带重构、清理或添加功能。

说明根本原因和拟议的修复方案，然后询问：“我可以实施此修复吗？”未经批准不得修改任何代码——紧急流程的审计记录应在更改实施之前批准，而不是事后补批。

---

阶段 4b：实施（仅限批准后）

实施已批准的最小更改。使用 project.yaml 中的 commands.test，针对受影响的系统运行定向测试，以验证修复（如果测试运行器允许，可缩小到受影响的测试套件）——绝不要凭记忆写测试运行器命令，因为这样会漏掉引擎所需的标志（gdUnit4 没有 --remote-debug tcp://127.0.0.1:0 会挂起）。检查相邻系统是否出现回归。如果未设置 commands.test，或没有测试覆盖受影响的系统，请说明这一点，并在热修复记录的 Testing 部分注明 Tests: NOT RUN — [reason]；阶段 5b 的 QA 关卡随后负责验证。

在热修复记录中补充根本原因、修复详情和测试结果。

---

阶段 5：征集批准

使用 Agent 工具并行请求签核：

• subagent_type: lead-programmer — 审查修复的正确性和副作用
• subagent_type: qa-tester — 对受影响的系统运行定向回归测试
• subagent_type: producer — 批准部署时间和沟通计划

三方均须返回 APPROVE 才能继续。如果任何一方返回 CONCERNS 或 REJECT，不得部署——先提出问题并解决。

---

阶段 5b：QA 重新准入门槛

获得批准后，确定部署热修复前所需的 QA 范围。通过 Agent 启动 qa-lead，并提供：

• 热修复说明和受影响的系统
• 阶段 5 的回归测试结果
• 所有涉及变更文件的系统列表（使用 Grep 查找调用方）

询问 qa-lead：完整冒烟检查是否足够，还是此修复需要有针对性的 team-qa 检查？

根据结论执行：

• 冒烟检查足够 — 针对热修复构建运行 /smoke-check。如果结果为 PASS 或 PASS WITH WARNINGS，则进入阶段 6（将警告记录到热修复记录中）。 如果结果为 FAIL，则不要部署：带着失败的检查项返回阶段 4，在那里获得 修订后修复方案的批准，实施方案（阶段 4b），然后重新执行阶段 5 的批准流程—— 包括 qa-tester 的回归测试——以及此 QA 步骤。导致冒烟测试套件失败的热修复 是第二起事故，而不是修复。
• 需要有针对性的 QA 检查 — 运行 /team-qa feature: [affected-system]，范围仅限变更的系统。如果 QA 返回 APPROVED 或 APPROVED WITH CONDITIONS，则进入阶段 6；如果返回 NOT APPROVED 或 BLOCKED，则按上述冒烟检查 FAIL 处理。
• 需要完整 QA — 涉及核心系统的 S1 修复可能需要完整的 /team-qa sprint。这会延迟部署，但能防止有问题的补丁上线。

如果 QA 步骤返回 NOT ASSESSED，说明门槛检查并未运行——应将其视为未满足， 而非已满足。 /smoke-check 会在测试套件从未执行时返回此结果；如果某个周期没有产生已执行的证据，/team-qa 也会返回此结果。无论来自哪个技能，NOT ASSESSED 都不代表通过——而且在时间压力下，宽松解读往往显得合理， 这正是要在此明确写出的原因。要么获取缺失的结果——结论会指出如何才能运行检查——要么明确将决定提交给相关负责人，作为一项部署未经验证热修复的决定，而不是让门槛悄无声息地放行。将该决定——由谁作出，以及原因——记录在热修复记录的 Testing 部分。

不要跳过此门槛。导致其他问题的热修复比原始缺陷更糟。

---

阶段 6：更新 Bug 状态并部署

停止 — 部署无条件需要明确批准。 合并 hotfix 并为补丁版本打标签，是此技能中唯一不可逆的操作，因此必须经过审批，即使创建分支（可逆）已经如此。在任何合并、打标签或部署之前，使用 AskUserQuestion：

• 提示词："Hotfix 已验证并获批准。要合并到 [targets]、为 [patch tag] 打标签并部署吗？" — [targets] 为 main，如果该版本有 release/* 分支，也包括该分支
• 选项：[A] 是 — 合并并部署 / [B] 仅合并到 main — 暂缓发布 / [C] 到此为止

无论 modes.automation 的值为何，包括 autonomous，都必须遵守此要求。紧急流程恰恰是最可能发生未经审查的不可逆操作、且最难恢复的情形。

选择 [A]：将 hotfix 分支合并到 main；如果该版本有 release/* 分支，也合并到该分支；为补丁版本打标签（下一个补丁版本，例如 v1.2.0 → v1.2.1），标签应指向已修复的构建——如果有 release/* 分支，则指向该分支的 HEAD，否则指向 hotfix 分支的 HEAD——并部署该标签，而不是 main 的 HEAD。选择 [B]：仅合并到 main——不合并到发布分支、不打标签、不部署。选择 [C]：停止——不合并、不打标签、不部署，也不更新 bug 文件；hotfix 记录的 Status 保持为 IN PROGRESS，并明确说明这一点。

除非你亲自验证，否则 backport 就不算已验证。 frontmatter 标示着 "backport verified"。合并后，确认修复已包含在 main（主干）中——如果该版本有 release/* 分支，也要确认修复已包含在该分支中——并说明验证结果。未 backport 的 hotfix 意味着从 main 打标签发布下一个版本时，bug 会再次出现；这是最常见的 hotfix 回归问题。

如果存在原始 bug 文件，请更新该文件——像 /bug-report verify 一样，按编号在 production/qa/bugs/ 中查找。先询问："我可以使用以下修复记录更新 production/qa/bugs/[bug file]，并将其 Status 设置为 Fixed — Pending Verification 吗？"

## Fix Record
**Fixed in**: hotfix/[branch-name] — [commit hash or description]
**Fixed date**: [date]
**Status**: Fixed — Pending Verification

在 bug 文件头部设置 **Status**: Fixed — Pending Verification。

输出部署摘要。其标题根据阶段 6 的回答确定——选择 [A] 时为 Hotfix Deployed: [short-name]，选择 [B] 时为 Hotfix Merged to main — release held: [short-name]；选择 [B] 时，结尾行省略 Tag，因为没有创建标签：

## Hotfix Deployed: [short-name]

**Severity**: [S1/S2]
**Root cause**: [one line]
**Fix**: [one line]
**QA gate**: [Smoke check PASS / Team-QA APPROVED / NOT ASSESSED — [why, and whose
             explicit decision it was to deploy anyway]]
**Approvals**: lead-programmer ✓ / qa-tester ✓ / producer ✓
**Backport**: [verified present on `main` (and the `release/*` branch, if the
              release has one) — or NOT VERIFIED, with what was not checked]
**Rollback plan**: [from Phase 2 record]

Merge to: [targets] · Tag: [patch tag]
Next: /bug-report verify [BUG-ID] after deploy to confirm resolution

规则

• Hotfix 必须是修复问题所需的最小改动——不得清理或重构
• 每个 hotfix 都必须在部署前记录回滚计划
• Hotfix 分支必须从其所修复的版本创建——从该版本的标签创建；如果有 release/* 分支，则从该分支创建。hotfix 必须合并到 main（主干），并且仅在 release/* 分支存在时合并到该分支；补丁版本必须打标签
• 所有 hotfix 都必须在 48 小时内进行事后审查
• 如果修复复杂到需要超过 4 小时，请上报给 technical-director

---

阶段 7：部署后验证

部署后，运行 /bug-report verify [BUG-ID]，确认修复已解决已部署构建中的问题。

如果已确认修复：运行 /bug-report close [BUG-ID] 正式关闭该问题。 如果问题仍存在：hotfix 失败——立即重新打开问题，评估是否回滚，并上报。 如果无法验证：修复尚未确认——不要关闭 bug；在已部署的构建中按复现步骤操作，然后再次运行 /bug-report verify [BUG-ID]，并回答其手动操作问题以确定结果。

在 48 小时内安排事后审查。/retrospective 用于审查冲刺或里程碑，而不是事件：使用 .claude/docs/templates/incident-response.md 记录审查，并在下次 /retrospective 时提出审查中的经验教训。

使用 AskUserQuestion：

• 提示词："Hotfix 已完成。下一步是什么？"
• 选项：
  • [A] 运行 /smoke-check 验证修复
  • [B] 运行 /patch-notes 记录此 hotfix
  • [C] 到此为止