auto-debug

Files (1)

• SKILL.md

SKILL.md (first lines)

# Auto Debug

Auto Debug 是一个证据驱动的调查循环。用户可能只需要一个结论；不要默认必须实施修复。本 skill 只定调查纪律，不描述任何强制执行机制。

## 先理解这些 ID

CLI 为调查对象分配稳定 ID。ID 不是状态，也不是执行命令；它只是后续命令引用对象的名字。

| ID | 对象 | 示例 | 含义 |
|---|---|---|---|
| `CASE-1` | Case | `CASE-1` | 一次完整调查的容器，由 `case init` 的位置参数指定 |
| `DL-001` | Deliverable | `DL-001` | 用户要求的一个交付物 |
| `CR-001` | Criterion | `CR-001` | 某个 Deliverable 的第一个验收项，由 `deliverable add` 按顺序生成 |
| `CL-001` | Claim | `CL-001` | 一个可检验的原因或解释 |
| `EX-001` | Experiment | `EX-001` | 一份已规划的实验定义 |
| `EX-001-A001` | Attempt | `EX-001-A001` | `EX-001` 的第一次实际执行；重试会产生 `A002` |
| `EV-001` | Evidence | `EV-001` | 一条不可变的观察事实 |
| `AR-001` | Artifact | `AR-001` | 一个日志、脚本、IR、报告或其他存储载体 |

例如：

```text
EX-001
├── procedure          已保存的实验脚本
└── EX-001-A001        第一次执行
    ├── stdout.log
    ├── stderr.log
    └── execution.json
```

`EX-001` 是实验计划；`EX-001-A001` 是该计划的一次执行。`experiment run EX-001` 运行的是计划，不是手写的临时命令。

## Case 在哪里

Case 由用户经 `/debug <调查目标>` 创建，位于当前目录的 `.zoo/debug/<case-id>/`：

```text
当前目录/
└── .zoo/debug/
    └── CASE-1/
        ├── case.jsonl       权威追加记录，不直接编辑
        ├── summary.md       自动生成的恢复视图，不直接编辑
        └── artifacts/       脚本、日志、快照和附件
```

agent 禁止自主执行 `zdebug case init`。工作区没有 Case 时按正常流程调试，不要碰 zdebug 的 case 命令，也不要为了"开始自主调试"而造一个 Case。

如果当前目录下只有一个 Case，CLI 通常可以自动找到它。存在多个 Case 时，在命令中显式传入：

```bash
zdebug case status --case-id CASE-1
zdebug case status --case-dir /path/to/.zoo/debug/CASE-1
```

也可以从任意工作目录用 `--case-dir` 操作指定的 Case。所有写入都必须通过领域 CLI 完成；不要直接编辑 `case.jsonl` 或 `summary.md`。

## 四个核心概念

- **Deliverable**：用户要求获得的结果，以契约和验收项表达。只需要原因时，Deliverable 不要求修复代码。
- **Claim**：不可变、有范围的解释。陈述发生变化时创建新的 Claim，并使用 `refines`、`contradicts` 或 `supersedes` 表达关系。
- **Experiment**：预先声明的问题和过程。规划与运行是两个独立操作。
- **Evidence**：不可变的观察，包含来源、上下文和 artifact 引用。

关系通常是：

```text
Experiment 产生执行记录
    ↓
Agent 从执行记录提炼 Evidence
    ↓ supports / challenges
Claim
    ↓ 被验收项引用
Deliverable
```

CLI 负责维护 Case 记录和校验引用；Agent 负责技术解释。Core 不会根据退出码自动判断根因，也不会替 Agent 选择下一项实验。

## 核心循环

1. 定义所需的 Deliverable 及其验收标准。
2. 使用常规源码和 shell 工具自由探索。探索过程不必记录。
3. 提出有范围且可证伪的 Claim。
4. 在运行前规划 Experiment。记录问题、受控条件、单一变量、过程脚本和判读规则。
5. 通过 `zdebug experiment run EX-001` 运行不可变的过程脚本。
6. 将观察结果明确提炼为 Evidence。执行成功不等于技术结论成立。
7. 用 `supports` 或 `challenges` 建立 Evidence 与 Claim 的关系；Claim 的评估强度不能超过证据支持的范围。
8. 将每项 Deliverable 标记为 `satisfied`、`blocked` 或 `waived`。只有用户请求的交付物已经诚实结清后，才能关闭 Case。

收敛由外部验证判据决定，不由自述决定。判据转绿后循环沉默（converged），但只要 Case 保持 OPEN，每轮停稳仍会重跑验证实验作回归监视。

## 最小流程

### 1. 恢复现状

接手已存在的 Case 时，先看机器记录的现状：

```bash
zdebug case status
```

随后读 `.zoo/debug/<case-id>/summary.md` 了解目标、已有 Claim、实验与证据。不要凭对话记忆重建"试过什么、排除了什么"——agent 会忘，仓库不会忘。需要机器可读现状时加 `--json`。

### 2. 定义交付物

```bash
zdebug deliverable add \
  --title "解释问题原因" \
  --contract "给出有范围且有证据支持的原因" \
  --criterion "定位最早异常阶段" \
  --criterion "说明证据边界和替代解释"
```

这会创建 `DL-001`，并按参数顺序创建：

```text
CR-001: 定位最早异常阶段
CR-002: 说明证据边界和替代解释
```

From 418-teapot/ZooKeeper, MIT.

More from 418-teapot/ZooKeeper