investigate

Files (2)

• SKILL.md
• analysis-report.md · templates/

SKILL.md (first lines)

# Investigate

## 角色定义

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

默认顺序固定为：

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

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

## 触发条件

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

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

## 前置检查

开始调查前先确认：

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

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

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

## 调查流程

### Step 1: 固定问题陈述

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

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

### 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`: 缺少关键上下文、权限或稳定复现条件

## 禁止行为

- 未形成可验证假设前直接修改代码
- 用“大概率是”替代证据
- 为了让测试通过而绕过失败条件

From blackplume233/actant-skills, MIT.

More from blackplume233/actant-skills