bugfix

用途

bugfix 是 keel 项目专用的 Bug 修复技能，采用测试先行的修复流程，确保每个修复都有回归测试保护和完整记录。它不适用于新功能开发（用 /feature）或代码质量改进（用 /insights），非 keel 项目的修复应使用 dev-flow。

触发条件

用户报告 Bug 或问题
用户提到“修复”“bug”“issue”“崩溃”“报错”
用户提供 Issue 编号或链接
测试执行失败（UT/IT/E2E）

核心理念

先证明 Bug 存在（失败测试），再修复代码，最后证明 Bug 已修复（测试通过）。每个 Bug 都要记录，形成知识沉淀。

运行模式

/bugfix：标准修复，自动评估复杂度
/bugfix BUG-XX realign：规范升级回扫，按 BUG-XX 过滤调度相关 skill --realign，仅补齐已完成 bug 流程的规范差距，不触发再修复。共享契约见 ../pipeline/references/realign.md，推荐用户入口 /pipeline realign。

复杂度判断

简单：单文件/单函数、原因明确，本 Skill 直接修复
复杂：多模块、需拆分步骤、原因不明，必须走 /dev-tasks

复杂度评估使用 AskUserQuestion 确认，命中“涉及多个模块/文件”“原因不明确”“修复可能影响其他功能”“需要多个步骤”任一项即必须走任务拆分，仅当用户明确选择“继续简单流程”时才允许跳过。

工作流程

理解 Bug + 评估复杂度：复杂 Bug 必须 /dev-tasks 拆分任务；简单 Bug 继续。收集 Bug 描述、复现步骤、预期行为、实际行为、发现来源、关联功能（F-XXX / AC-XXX 或 baseline）、Issue 编号等信息，信息不足时用 AskUserQuestion 询问。基线项目（有 00-baseline.md 且无 01~04）的 Bug 关联功能填 baseline，回归测试仍必须写，代码内不写编号标注。
定位代码 + 根因确认：通过关键词搜索、错误信息搜索、测试定位、用户指定等方式定位，向用户确认。原因不明时进入根因诊断门。
编写失败测试（证明 Bug 存在）：测试命名规范为 should [预期行为] when [触发条件]，结构使用 describe/it 的 Arrange-Act-Assert。运行测试确认失败则 Bug 已复现，通过则需重新确认。
修复代码：最小改动、不引入新功能、遵循现有风格，参考 /code-quality 约束。
运行测试：运行新增测试与全部测试，新测试通过且全部通过则修复完成，否则返回步骤 4 或检查回归。
记录 Bug：追加到 docs/devdocs/05-bugfix-log.md，包含发现来源、关联功能、Issue、严重程度、修复日期、状态、问题描述、复现步骤、根因分析、解决方案、回归测试、经验教训等。
提交：询问用户是否提交，生成 fix() 提交信息，遵循 /commit-convention。

根因诊断门（原因不明时必过）

目的是禁止“未理解就修”（shotgun debugging）。步骤包括：固定稳定复现基线；列出候选根因假设并按可能性排序，每条写明“若成立应观察到什么”；对首选假设做最小仪器化验证；假设被证实则根因成立进入失败测试，被证伪则取下一条。根因未经证实禁止开始修复代码。连续 2 轮假设全部证伪时必须确认，用户可选择转 /dev-tasks 拆分诊断任务，或提供新线索后重进诊断门。若环境提供跨会话历史检索（如 /mem-search），先查同症状此前是否修过，查询需带代码标识符，历史命中不替代步骤 3-4 的证实。

输出文件与编号规则

Bug 修复日志：docs/devdocs/05-bugfix-log.md
Bug 记录编号前缀 BUG，格式 BUG-XXX，编号延续现有文档中的最大编号，扫描方法按 id/scan-word-boundary（grep -owhE 整词 + sort -n 数值序）。

提交

workspace_context.mode 不是 inline 时提交走 N+1 仓协议（含 detached HEAD 前置门与跨仓 Recovery），见 workspace-topology/references/protocol.md。修复代码提交进对应子模块（commit message 沿用该仓风格、不带 BUG-XX 编号），bugfix 日志提交进外壳仓。mode 为 linked 时代码根不归本仓所有，各仓各自提交、不 bump 指针。提交信息格式为 fix(<scope>): <简述问题>，包含根因、修复、测试，并附 BUG-XXX 与 Fixes #<issue-number>。

与测试用例的闭环

测试执行失败触发 /bugfix，记录 BUG-XXX（关联测试编号）、修复代码、新增回归测试、/sync 更新追溯矩阵。

编排规范（子 Agent 调度）

复杂 Bug 路径下，bugfix 调用子技能时必须通过 Task tool 启动子 Agent：复杂 Bug 拆分调度 /dev-tasks，复杂 Bug 开发调度 /dev-workflow，文档同步调度 /sync。调度原则包括上下文隔离、摘要传递、异常回退、不自行排障。简单 Bug 因流程短，直接在 bugfix 上下文内执行，不启动子 Agent。

Skill 协作

复杂 Bug 拆分用 /dev-tasks，回归测试设计用 /test-cases，需求缺失用 /requirements，测试编写用 /testing-guide，代码修改用 /code-quality，文件操作用 /git-safety，提交信息用 /commit-convention，文档同步用 /sync。

约束

流程约束：必须先编写失败测试再修复代码；原因不明时必须过根因诊断门；测试未通过时不得提交；复杂 Bug 走 dev-tasks + dev-workflow 时必须通过 Task tool 启动子 Agent。
记录约束：每个 Bug 必须记录到 05-bugfix-log.md，必须记录发现来源、根因分析、解决方案，必须关联回归测试编号。
追溯同步约束：修复完成后必须执行 /sync，新增回归测试必须登记到 03-test-*.md 追溯矩阵。
测试约束：禁止弱断言。
提交约束：提交信息包含 BUG-XXX 编号。

子 Agent 摘要格式

当本 Skill 作为子 Agent 运行时，返回结构化摘要，包含 skill、status、summary（headline、details 含 bug_id、complexity、related、test_added、commit_hash）、blockers、output_files、new_ids、next_recommended 等字段。

特殊情况

Bug 无法复现：测试通过、Bug 未能复现，可能原因包括复现条件不完整、Bug 已在其他提交中修复、环境差异。建议确认复现步骤、检查最近相关提交、与报告者确认环境信息。
复杂 Bug：检测到复杂 Bug 必须使用任务拆分，默认必须走任务拆分，仅当用户明确选择“继续简单流程”时才允许跳过。
Bug 暴露设计缺陷：先用最小改动修复当前 Bug，记录设计缺陷到“经验教训”，创建改进建议（可选 /insights），使用 /refactor 进行系统性改进。

语言规则

支持中英文提问，统一中文回复。