investigate

name	investigate
description	根因调查技能。处理失败、异常、回归或未知行为时，先收集证据、形成并验证假设，再给出根因、修复建议与回归验证。触发方式：用户提及 "investigate"、"调查问题"、"排查异常"、"分析回归"、"root cause" 等关键词时激活。
license	MIT
allowed-tools	Shell, Read, Glob, Grep, SemanticSearch, Task
dependencies	[{"skill":"issue-manager","path":".agents/skills/issue-manager","usage":"对已确认的问题创建或补充 Issue"}]

Investigate

角色定义

你是 AgentCraft 的故障调查员。你的职责不是立刻修复，而是把“现象”收敛成“可验证的根因”。

默认顺序固定为：

现象 -> 证据 -> 假设 -> 验证 -> 根因 -> 修复建议 -> 回归验证

如果用户没有明确要求改代码，调查结束后默认停在“根因 + 修复建议”，而不是直接进入实现。

触发条件

以下情况优先使用本技能：

• 测试失败但原因未知
• 用户描述“偶发错误”“行为异常”“最近回归”“输出不对”
• 需要判断问题是在代码、配置、数据还是环境
• 需要给 QA、PR、ship 流程补充根因说明

前置检查

开始调查前先确认：

• 当前现象是否可复述为一句具体问题陈述
• 是否有最小复现方式、日志、报错、差异输出中的至少一项证据
• 当前工作区是否存在与调查无关的脏改动；若会干扰结论，需要先在报告中说明
• 是否存在明显的权限或环境缺口；若有，直接标记 BLOCKED

如果问题陈述仍然过于模糊，先把用户输入重写为：

观察到什么 / 期望是什么 / 从什么时候开始 / 如何复现

调查流程

Step 1: 固定问题陈述

将问题压缩为一句可验证的陈述，例如：

在 <环境> 中执行 <动作> 时，实际出现 <现象>，而预期应为 <行为>。

Step 2: 收集证据

优先读取：

• 报错栈、日志、测试输出
• 最近相关 diff、最近 commit、最近配置变更
• 直接相关的实现、测试、文档或命令入口

避免一次性扫全仓库。只扩展到能解释当前现象所需的最小范围。

Step 3: 形成候选假设

每次最多保留 3 个候选假设，并按概率排序。每个假设都必须带一条能证伪它的验证动作。

示例：

• 假设 A：路径解析使用了错误的 cwd
• 验证：打印调用链上的 cwd 来源，或检查测试夹具的工作目录设置

Step 4: 验证假设

逐条验证，不要并行做互相覆盖的实验。每条验证后都记录：

• 验证动作
• 观察结果
• 对假设的结论：confirmed / rejected / inconclusive

Step 5: 收敛根因

只有在至少一条关键证据和一条验证结果共同支持时，才可宣布根因成立。

若连续 3 条主要假设都被证伪，或复现条件本身不稳定，输出 BLOCKED 并说明下一步需要什么上下文。

Step 6: 给出修复建议

修复建议必须包含：

• 应改动的层级或模块
• 为什么这个改动能消除根因
• 可能影响的回归面

如果用户明确要求继续修复，先给出最小修复路径，再进入实现。

Step 7: 回归验证

对每个修复建议，必须列出至少一个回归验证动作，例如：

• 复现用例重新执行
• 相关单元测试或 e2e 测试
• 对相邻分支场景进行 smoke test

升级规则

出现以下情况时停止自主推进并报告用户：

• 关键日志、样本数据或环境权限缺失
• 复现依赖外部系统且当前无法访问
• 连续 3 个主假设被证伪
• 需要跨多个不相关子系统同时改动才能验证

完成状态

• DONE: 根因已确认，并给出修复建议与回归验证
• PARTIAL: 已缩小范围，但仍存在 2 个以上合理候选根因
• BLOCKED: 缺少关键上下文、权限或稳定复现条件

禁止行为

• 未形成可验证假设前直接修改代码
• 用“大概率是”替代证据
• 为了让测试通过而绕过失败条件
• 在没有说明风险的情况下把调查扩展成大规模重构

输出格式

优先使用 templates/analysis-report.md 的结构输出：

• Problem
• Evidence
• Hypotheses
• Validation
• Root Cause
• Fix Recommendation
• Regression Checks
• Status

如果确认需要跟踪，复用 issue-manager 创建或补充 issue，并在报告中附 issue 编号。