| name | bugfix |
| description | Locate a defect, make the smallest safe fix, and collect targeted validation evidence with Engineer/QA boundaries. |
bugfix
面向已知缺陷或可复现异常，按 Engineer/QA 边界完成缺陷定位、最小修复和定向验证，不承担需求扩展、架构重构或无关清理。
用法
/bugfix <缺陷描述或复现路径>
目标
- 明确缺陷现象、影响范围和预期行为
- 定位最可能根因与受影响文件
- 实施最小必要修复
- 输出可复现的验证证据
适用场景
- 已有测试失败、命令报错或用户提供复现路径
- 现有功能行为与任务、PRD 或文档验收标准不一致
- 需要快速修复单点缺陷并保留清晰证据
不适用场景
- 新功能开发
- 大范围重构
- 无明确复现路径的产品方向讨论
- 需要人工决策的需求取舍
执行流程
- 确认输入：记录缺陷描述、复现路径、预期行为、实际行为和相关文件；缺失关键输入时先向用户澄清。
- 复现或定位：优先运行最小复现命令、定向测试或读取相关日志；无法复现时说明已检查路径和剩余不确定性。
- 根因判断：把现象映射到具体代码、配置或文档约束，说明为什么这是最可能根因。
- 最小修复：只修改修复该根因所必需的文件和逻辑，不做顺手重构、风格整理或无关优化。
- 定向验证：运行与缺陷直接相关的测试、命令或文件检查；验证失败时回到定位或修复步骤。
- 验收证据：输出修复范围、验证命令、关键结果和仍需关注的风险。
执行规则
- 先确认缺陷描述、复现路径、预期行为和相关文件；信息不足时先澄清。
- 默认只修改触发缺陷所必需的最小文件范围。
- 禁止借 bugfix 做无关重构、格式化、依赖升级或顺手优化。
- 修复后必须运行定向验证，验证失败不得给出通过结论。
- 输出必须包含根因、修复范围和验证证据。
- 根因不明确时不得扩大修复范围，只能记录假设、证据和下一步定位建议。
示例
/bugfix tests/test_metrics.py 中 run_metrics totals 断言失败/bugfix CLI 执行 opc runs trace 报 KeyError，复现命令为 python -m opc.cli runs trace latest
输出骨架
[缺陷现象] ...
[复现路径] ...
[预期行为] ...
[根因判断] ...
[修复范围]
- 文件：...
- 变更：...
[验证命令 / 检查方法]
- ...
[验证结果] 通过 / 不通过
[验收证据]
- 标准 1 → 通过 / 不通过（证据：path:line 或命令关键输出）
[后续风险] ...
验收标准
- 至少能从输入中识别缺陷现象、复现路径和预期行为
- 修复范围只包含与根因直接相关的文件
- 输出包含根因判断、验证命令和验收证据
- 若验证失败，结论必须是“不通过”并说明退回步骤
验收
- 只覆盖缺陷定位、最小修复和定向验证
- 明确 Engineer/QA 责任边界
- 禁止超范围重构的规则清晰可检查
- 输出包含根因和验证证据
