用途
bugfix 是一个基于根因分析(root cause)的一次性缺陷修复技能。它不直接改代码,而是先完成完整的调查流水线,再把修复工作委派给 /execute。触发方式为:
/bugfix "error description"
核心原则(The Iron Law)
- 未经根因调查,不得进行任何修复(NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST)。
- 无证据不得宣称完成。
- 3 次尝试失败后必须停止。
主要流程
技能始终运行完整的调查加执行流水线,没有 SIMPLE/COMPLEX 分支。整体分为五个阶段:
Phase 1:DIAGNOSE(诊断)
- 解析输入:提取缺陷描述、错误输出(堆栈、测试失败日志)、上下文(相关文件、近期改动)。
- 初始化调试状态:使用会话 ID 生成 slug,创建 debug-state.md,记录症状(Phase 1 后不可变)。
- 并行调查:始终并行调度 debugger 与 verification-planner 两个代理。debugger 负责按调查协议分类缺陷类型、回溯根因、评估严重程度;verification-planner 负责给出证明修复生效的验证命令(仅 Tier 1-3 的 Auto 项,不内联 VERIFICATION.md,不含 Tier 4 沙箱项)。收到 debugger 结果后更新 debug-state.md 的诊断段。
- Gap 分析:debugger 结果返回后始终运行 gap-analyzer,核对根因与症状的区分是否正确、拟议修复是否会破坏其他区域、是否存在同模式的类似缺陷。
- 爆炸半径快速扫描:在得到根因位置后,提取函数/模块名进行基于 grep 的结构扫描,统计 total_files、callers、importers、tests、hot_path。使用 -F(固定字符串)避免正则注入;符号为空或格式异常则跳过该项信号,不使该阶段失败。资料同时注明盲区:grep 无法覆盖动态派发、反射以及非 JS/Python 的 import 形式,计数低不代表安全。
- 分诊建议:根据扫描结果给出路由提示(首个匹配生效)——触及热门路径(auth/payment/migration/schema)建议 /specify;严重程度为 COMPLEX 且 callers 超过 10 且超过仓库文件数的 5% 建议 /specify;根因文本含不确定标记(?、추정、possibly、may、unclear)建议 /discuss;以上都不满足则适合 bugfix。该提示仅为建议。
- 用户确认:通过 AskUserQuestion 展示缺陷类型、根因(file:line + 一行描述)、拟议修复、验证命令、假设、Gap 分析关键警告、爆炸半径与分诊建议,选项包括:继续 bugfix(若分诊建议非 bugfix 则显示为“覆盖分诊继续”)、切换 /specify、切换 /discuss、根因不同(补充信息后重跑 Step 1.2)、停止。选择 /specify 时会生成 requirements.md 骨架并附上 debugger 报告与爆炸扫描,随后退出 bugfix。
Phase 2:REQUIREMENTS GENERATION(需求生成)
- 将诊断结果转换为 requirements.md 格式。该文件是 /execute 消费的标准格式,并在失败时作为 /specify 的升级上下文。
- 使用
hoyeon-cli req init ${SPEC_DIR} --type bugfix --goal "Fix: {bug description}"初始化,创建带存根模板的 requirements.md。 - 使用 Write 工具覆写完整需求内容,包含 type/goal/non_goals 头部、R-B1 需求(含 R-B1.1、R-B1.2 等子需求,采用 given/when/then 形式)、R-T1 最小差异约束以及 Constraints(最小差异 <5%、修复根因而非症状、不做修复以外的重构)。
- 映射规则:把 debugger 的复现步骤转换为 GWT;若识别到边界情况或类似问题则各加一条子需求;包含修复范围护栏的约束段。
- 注册:通过
hoyeon-cli session set --sid $SESSION_ID --spec "$SPEC_DIR"登记,并在 debug-state.md 中记录 spec_dir。
Phase 3:EXECUTE(执行)
将 requirements.md 交给 /execute,由 Execute2 从 spec 目录读取 requirements.md 并在内部推导 plan.json。execute 负责:通过 AskUserQuestion 提示用户选择 dispatch / work / verify;按所选 dispatch 模式派发 worker;轮级提交;按所选 verify 深度执行验证配方;输出最终报告。执行成功进入 Phase 5,中止则进入 Phase 4。
Phase 4:RESULT HANDLING(结果处理)
- 读取失败上下文(execute 的 HALT 输出,或 context 目录的 audit.md、issues.json)。
- 重试:attempt 计数加一,最多 3 次;达到上限进入 Step 4.5 熔断。
- 停滞检测(attempt 大于等于 2):对比先前失败信息,识别 SPINNING(同一文件/组件连续失败)、OSCILLATION(A 失败→B 失败→A 失败)、NO_PROGRESS(每次失败不同,先前修复引发回归)三类模式,并给出对应的 retry_hint;无模式则提示需要不同方法、不要重复先前尝试。
- 更新需求并重新执行:在 debug-state.md 记录本次尝试结果与提示,更新尝试计数,将失败上下文追加进 requirements.md(Constraints 或 Known Issues),然后重新调用 execute。直接修改 plan.json 交给 /execute 处理,如需重置失败任务可用
hoyeon-cli plan list与hoyeon-cli plan task --status <task-id>=pending。 - 熔断:超过最大尝试次数后,将记录写入 .hoyeon/debug/{slug}.md(状态 ESCALATED),通过 AskUserQuestion 提供选项:切换 /specify(完整规划)、再试一次(不重置熔断)、停止。
Phase 5:CLEANUP & REPORT(清理与报告)
- execute 成功后,将报告写入 .hoyeon/debug/{slug}.md(状态 RESOLVED),含根因、修复、验证内容,并将 debug-state 状态更新为 resolved。
- 输出最终摘要:缺陷、根因(file:line)、尝试次数、Spec Dir、报告路径。
- QA 建议:通过 AskUserQuestion 询问是否运行 /qa 在浏览器/应用中验证修复且无回归。
升级路径
/bugfix(诊断 + requirements.md + execute)→ 熔断(3 次失败)→ 保存 requirements.md 与 .hoyeon/debug/{slug}.md → /specify(利用已有诊断上下文丰富需求)→ /execute(执行丰富后的需求)。由于 requirements.md 是标准格式,/specify 可读取并丰富既有需求,所有诊断上下文(约束、已知问题、GWT 场景)都会保留。
代理汇总
Phase 1 始终调用三个已有代理:debugger(根因分析、Bug Type 分类)、verification-planner(生成 Auto 项验证命令列表)、gap-analyzer(检查遗漏因素、风险评估);Phase 1.5 执行 Bash(git grep + wc -l)扫描。
限制
- 3 次尝试失败后必须停止,不会无限重试。
- 爆炸半径扫描基于 grep,无法覆盖动态派发、反射与非 JS/Python 的 import 形式,计数低不代表安全。
- 分诊建议仅供参考,最终路由由用户决定。
- 关于收费、价格、支持平台等信息,资料未提供。