ac-debug

name	ac-debug
description	问题诊断：定位报错与异常根因，按需并行取证，并在用户确认后执行最小修复与验证。
disable-model-invocation	true

Debug - 主线程诊断 + Subagents 取证

定位问题根因，必要时由 Claude 主线程统筹多个 subagents 并行取证；最终诊断、用户沟通、代码修复与验证均由主线程完成。

使用方法

/ac-debug <问题描述>

角色分工

角色	职责
Claude（主线程）	收集问题、决定是否启用 subagents、整合证据、输出诊断、等待确认、执行修复
subagents	并行检索调用链、日志线索、配置/测试影响等证据，不修改代码

---

执行约束

工作目录：

• 如果用户通过 /add-dir 添加了多个工作区，先用 Glob/Grep 确定任务相关的工作区
• 如果无法确定，用 AskUserQuestion 询问用户选择目标工作区
• 在当前会话内完成诊断与修复，不依赖外部模型或额外会话

subagents 使用条件：

• 适用：错误路径不清、涉及多个模块、日志/堆栈很多、需要并行排查多个方向
• 优先：使用只读 subagents 做调用链检索、错误点上下文收集、配置/测试影响分析
• 不适用：报错点明确、单文件小问题、两三次检索即可收敛的简单问题

重要：

• 不调用任何外部模型、后台任务或额外 Bash 编排
• subagents 只做检索与取证，不做代码修改，不直接给用户下最终结论
• 已委托给 subagents 的搜索或分析内容，主线程不要重复执行
• 最终诊断结论必须由主线程统一输出
• 修复前必须先向用户展示诊断结果并等待确认

---

执行工作流

问题描述：$ARGUMENTS

🔍 阶段 0：Prompt 增强（可选）

[模式：准备]

分析 $ARGUMENTS 的意图、缺失信息、隐含假设，补全为结构化需求（明确目标、技术约束、范围边界、验收标准），后续诊断时优先使用增强后的需求。

🔎 阶段 1：上下文收集与并行取证

[模式：研究]

1. 主线程先收集最小必要信息：错误日志、堆栈、复现步骤、相关文件
2. 若问题较简单，直接继续诊断
3. 若问题跨模块或线索很多，按需并行启动 subagents，典型拆分为：
   • 调用链排查：定位报错路径、入口和相关调用方
   • 证据收集：整理日志、堆栈、异常分支、边界条件
   • 影响面排查：检查配置、测试、依赖模块、最近改动的关联面
4. subagents 返回证据、定位和可疑点后，由主线程统一收集

🔬 阶段 2：主线程诊断

[模式：诊断]

1. 基于主线程与 subagents 收集到的证据进行诊断
2. 输出诊断假设（按可能性排序），每个假设包含：
   • 原因
   • 证据
   • 验证方式
   • 修复建议
3. 必要时补充一轮定向检索，直到诊断范围收敛

🔀 阶段 3：假设整合

[模式：验证]

1. 交叉验证代码、日志、堆栈与复现步骤
2. 筛选 Top 1-2 最可能原因
3. 明确最小修复路径与验证策略

⛔ 阶段 4：用户确认（Hard Stop）

[模式：确认]

## 🔍 诊断结果

### 关键证据
- <证据 1>
- <证据 2>

### 综合诊断
**最可能原因**：<具体诊断>
**验证方案**：<如何确认>
**修复方向**：<准备怎么改>

---
**确认后我将执行修复。是否继续？(Y/N)**

⚠️ 必须等待用户确认后才能进入阶段 5

🔧 阶段 5：修复与验证

[模式：执行]

用户确认后：

1. 由主线程根据诊断实施修复
2. 运行最小相关范围的测试或验证步骤
3. 若验证失败，先修复回归问题再交付

---

关键规则

1. 证据优先 – 以代码、日志、堆栈与复现信息为准
2. 主线程收口 – 最终诊断、修复与验证均由当前会话主线程完成
3. subagents 只做取证辅助 – 按需使用，不默认开启，不修改代码
4. 用户确认后修复 – 修复前必须获得确认