需要按范围修复 bug、Hook、依赖或 PR 评论时，用…

适用于需要按范围（bug/hook/依赖/PR 评论）编排调查、诊断、实现、测试与提交的修复任务。

适用场景

解决思路

1. 用 `/fix <scope> [options] [description]` 调用；若无参数或参数不全，进入 AskUserQuestion 问题流程。
2. Phase 0：询问“What would you like to fix?”，选项 Help me choose (Recommended)、Bug、Hook、Dependencies、PR Comments；映射：Bug→scope=bug，Hook→scope=hook，Dependencies→scope=deps，PR Comments→scope=pr-comments；Help me choose 继续 Phase 1-4。
3. 如果用户通过 Other 回答不清晰，询问澄清“Did you mean...”，选项 Help me choose、Bug、Hook、Neither。
4. Phase 1：询问“What kind of issue are you dealing with?”，选项 Something is broken/not working、Claude Code hook not firing、Import/dependency errors、Need to address PR feedback；映射到 scope bug/hook/deps/pr-comments。
5. Phase 2：询问“Can you describe the issue?”，自由文本，捕获错误消息、意外行为或 PR 链接。
6. Phase 3：询问“How should I investigate?”，选项 Diagnose and fix、Diagnose only (dry run)、Quick fix；映射：Diagnose only→--dry-run；Quick fix→跳过调查直接进入 spark agent。
7. Phase 4：询问“After fixing, should I...”，多选 Write a regression test、Commit the fix、Just fix, nothing else；映射：无 regression test→--no-test；无 commit→--no-commit。
8. 执行前显示总结：Scope、Issue、Chain、Options，并询问 Proceed? [Yes / Adjust settings]。
9. 按 scope 选择链：bug→debug -> implement_task -> test-driven-development -> commit；hook→debug-hooks -> hook-developer -> implement_task -> test hook；deps→dependency-preflight -> oracle -> plan-agent -> implement_plan -> qlty-check；pr-comments→github-search -> research-codebase -> plan-agent -> implement_plan -> commit。
10. 选项效果：--no-test 跳过回归测试创建；--dry-run 只诊断不实现；--no-commit 不自动提交。
11. Phase 1 Parse Arguments：用 Bash 解析 `SCOPE="${1:-bug}"`，NO_TEST/DRY_RUN/NO_COMMIT 默认为 false；遍历参数，匹配 --no-test、--dry-run、--no-commit 分别设为 true。
12. Phase 2 Investigation：生成 sleuth agent 并行调查，检查日志（应用日志、系统日志、构建/测试输出）、数据库状态（卡住/无效记录、schema 匹配）、Git 状态（最近提交、未提交更改、当前分支）、运行时状态（运行进程、端口冲突、环境变量）；返回结构化发现和证据。
13. Phase 3 Diagnosis Report：展示诊断报告，包含 scope、证据（日志/数据库/Git/运行时）、根因分析（主要假设、支持证据、替代假设）、建议修复（方法、要修改的文件及位置、风险等级和原因），并询问 Proceed with fix? (yes/no/modify)。
14. Phase 4 Human Checkpoint：必须等待用户确认；AskUserQuestion 问“Proceed with the proposed fix?”选项 yes/no/modify；modify 则收集新需求并更新方法；no 则创建诊断 handoff 并退出；--dry-run 则创建诊断 handoff 并在此退出。
15. Phase 4.5 Premortem：诊断批准后、实现前运行 `/premortem quick`；上下文 mode: quick、context: "Bug fix for {diagnosis.root_cause}"；检查是否破坏其他功能、是否可回滚、是否遗漏边界情况、是否匹配代码库模式、是否影响外部依赖；无 HIGH tigers 继续实现；有 HIGH tigers 则问用户 Accept risks and proceed、Modify approach to address risks、Research mitigation strategies；若 Research mitigations，按风险并行生成 scout + oracle，再重新呈现选项。
16. Phase 5 Implementation bug scope：生成 kraken agent，按 TDD 实现：1) 写失败测试复现 bug；2) 实现最小修复通过测试；3) 如需要重构；4) 运行完整测试套件。
17. Phase 5 hook scope：生成 kraken agent：1) 检查 settings.json 中 hook 注册；2) 验证 shell 包装器存在且可执行；3) 用模拟输入手动测试 hook；4) 若修改 TypeScript 源码则重新构建；5) 验证 hook 正确触发。
18. Phase 5 deps scope：生成 kraken agent：1) 研究正确依赖版本；2) 创建实现计划；3) 更新 lockfiles；4) 运行 dependency-preflight；5) 运行 qlty-check。
19. Phase 5 pr-comments scope：生成 kraken agent：1) 研究代码库获取上下文；2) 为每条评论创建实现计划；3) 实现更改；4) 提交并引用评论。
20. Phase 6 Regression Test（除非 --no-test）：生成 kraken agent：1) 写一个本应捕获此 bug 的测试；2) 验证测试在修复前代码上失败（心理验证）；3) 验证测试在修复后代码上通过；4) 测试应最小且聚焦。
21. Phase 7 Human Checkpoint (Verification)：AskUserQuestion 问“Fix implemented. Please verify and confirm.”选项 looks good、needs adjustment、revert；needs adjustment 则收集反馈并返回 Phase 5；revert 则运行 rollback 命令并退出。
22. Phase 8 Commit（除非 --no-commit）：生成 general-purpose agent，遵循 commit 技能：1) 用 git diff 审查更改；2) 创建描述性提交消息；3) 如适用引用 issue/ticket；4) 展示计划并等待确认；5) 执行提交。
23. 按 scope 的链细节 bug：sleuth 调查 → 人类检查点诊断 → premortem 快速风险检查 → kraken 实现（implement_task + TDD）→ kraken 回归测试 → 人类检查点验证 → commit。
24. hook 链：debug-hooks 结构化调查 → 人类检查点诊断 → premortem 快速风险检查 → kraken 实现（implement_task + hook-developer patterns）→ 手动测试 hook → 人类检查点验证 → commit。
25. deps 链：dependency-preflight 检查当前状态 → oracle 查找正确版本/替代方案 → plan-agent 创建修复计划 → 人类检查点诊断+计划审查 → premortem 快速风险检查 → kraken 实现（implement_plan）→ qlty-check → 人类检查点验证 → commit。
26. pr-comments 链：github-search 获取 PR 上下文 → research-codebase 理解上下文 → plan-agent 为每条评论规划 → 人类检查点计划审查 → premortem 快速风险检查 → kraken 实现（implement_plan）→ 人类检查点验证 → commit（引用 PR 评论）。
27. Handoff Creation：总是创建 handoff，即使 --dry-run；YAML 字段包括 session、ts、commit、branch、status、scope、options、issue（description、evidence）、diagnosis（root_cause、hypothesis、files）、fix（approach、files_modified、test_added）、verification（test_command、human_confirmed）、next；位置 `thoughts/shared/handoffs/fix/{scope}/{timestamp}_{description}.yaml`。
28. 示例用法：`/fix bug` 调查、诊断、实现、测试、提交；`/fix bug --dry-run` 调查、创建诊断 handoff、停止；`/fix hook --no-commit` 完整修复流程但在提交前停止；`/fix bug --no-test` 实现修复、提交、无回归测试；`/fix pr-comments` 获取 PR、创建计划、实现、提交。
29. 错误处理：调查无发现→询问用户更多上下文；用户拒绝诊断→根据用户输入细化假设；修复破坏其他测试→回滚、细化方法；用户拒绝验证→提供回滚或调整；提交失败→呈现错误、提供重试。
30. 集成技能：编排 debug/debug-hooks、sleuth、kraken、implement_task、test-driven-development、plan-agent、dependency-preflight、oracle/research-codebase、github-search、qlty-check、premortem、commit、create_handoff。
31. 检查点总结：诊断后确认根因（从不跳过）；premortem 后接受或缓解风险（无 HIGH tigers 可跳过）；修复后验证解决（从不跳过）；提交前审查更改（--no-commit 可跳过）。人类检查点用于防止错误修复、确保用户理解更改、捕捉只有人类注意到的边界情况。

适用边界 · 注意事项

• 不使用 Claude Code 或无法访问 Task 子代理及配套技能（sleuth、kraken、premortem、plan-agent 等）时。
• 问题不属于 bug、hook、依赖或 PR 评论四类，且不需要按范围编排修复流程时。
• 需要完全自动、无需人类诊断/验证检查点的端到端修复时（本工作流强制人工检查点）。