Paper Pilot Before Batch

---
name: paper-pilot-before-batch
description: |
  在执行任何 ≥ 30 条目的批量任务（批量改文件、批量核查引用、批量重命名、批量格式统一）之前，
  必须先在 3–5 个样本上跑一遍，把样本结果给用户看，确认逻辑正确后再推全量。
  Use when 用户请求处理"全部"、"所有"、"批量"、"逐个"某类对象，
  且对象数量 ≥ 30，或数量未知（"把整个目录的..."）。
---

# paper-pilot-before-batch：批量任务先小样本

## 核心理念

批量任务的可怕之处：跑错 1 个 = 跑错 100 个。
小样本花 1 分钟，全量跑错回滚要 1 小时。

> 批量是放大器。脚本对了，放大效率；脚本错了，放大灾难。

---

## 触发条件

满足任一条 → 触发：

- 用户说"全部"、"所有"、"每一个"、"逐个"、"批量"、"统一"
- 操作对象数量 ≥ 30（文件 / 段落 / 引用 / 行）
- 操作对象数量未知（"整个目录的"、"全篇的"、"剩下的"）
- 涉及修改性操作（不是只读 / 查询）

---

## 强制流程

```
检测到批量操作
        │
        ▼
随机抽 3–5 个样本（不要只取前 3 个，前 3 个常常是规整数据）
        │
        ▼
只对样本执行
        │
        ▼
把样本结果展示给用户：
  - 每个样本的"改动前 vs 改动后"
  - 每个样本的"判断依据"（为什么这样改）
        │
        ▼
明确问用户：
「这是 N 个样本的改法，逻辑对的话我推全量（共 M 个）。
有不对的请指出，我调整后重新跑样本。」
        │
        ▼
确认 → 全量（≥ 30 时配合 paper-parallel-audit 用并行 Agent）
不对 → 改逻辑 → 重新跑样本
```

---

## 抽样策略（不是随便抽）

抽样要覆盖**边界情况**：

- 1 个最常见的情况
- 1 个看起来可能出问题的情况（最长 / 最短 / 含特殊符号 / 跨行）
- 1 个完全不该被处理的情况（验证你的判定逻辑不会误伤）

不要 `head -3` —— 前 3 个常常是规整数据，跑过样本不代表跑过全量。

---

## 标准回复模板

> 这是个批量操作，共 **M 个对象**。
> 先抽 5 个样本跑一下，包括 1 个常见情况、1 个边界情况、1 个不该被改的情况。
>
> [样本 1] 改前 → 改后，依据：…
> [样本 2] …
> [样本 3] …
>
> 5 个看着对的话，我就推剩下的 **M-5 个**。
> 有看着不对的请指出来，我调整后重跑样本。

---

## ❌ 反例（书 §10）

用户：「把所有引用的格式按 GB/T 7714 统一一下。」（共 156 条）

**错误做法**：写一个正则脚本，一次性跑 156 条——结果发现：

- 部分引用里的"等"被当成 et al. 多处理了一次
- 部分中文姓名拼音被错拆
- 全部 156 条都错，且原始格式没存

**正确做法**：先跑 5 条样本（含 1 条中文姓名、1 条多作者带"等"、1 条单作者）→ 用户检查 → 修正脚本 → 再推 156 条。

---

## "可以跳过样本" 的极少数情况

- **纯只读**：批量统计、批量列出（不修改任何文件）
- **逐条用户确认**：每条都让用户点头才下一条（实质就是没批量）
- **数量 < 30 且每条 < 1 秒**：直接做完，结果可视

---

## Rationalization Table

| 念头 | 现实 |
|---|---|
| "我已经在脑子里推演过了，肯定对" | 推演 ≠ 实测。书里的 156 条惨案，AI 也"推演过" |
| "用户着急，跳过样本更快" | 跑样本 1 分钟 vs 跑错回滚 1 小时 |
| "这个任务很简单，正则一行就搞定" | 简单的正则吃掉的都是边界情况 |
| "我跑前 3 个验证一下" | 前 3 个不是样本，是规整数据 |
| "我备份了，跑错了能回滚" | 回滚是兜底，不是策略 |
| "用户说他相信我直接全量跑" | 仍然先 5 个样本，跑出来给他看 |

---

## Red Flags

- 你即将对 ≥ 30 个对象 / 文件循环调用 Edit / Write → 停，先样本
- 你写了一段 for 循环 / 正则替换准备 apply 全量 → 停，先样本
- 你想"先跑一半看看" → 一半不是样本，跑错就 50 个错的
- 用户说"直接跑全量" → 仍然先 5 个样本，把结果给他看

---

## 配套 skill

- 全量阶段如果 ≥ 30，配合 `paper-parallel-audit` 用并行 Agent
- 修改性操作前必须 `paper-confirm-before-doing` 已经确认过方案

---

## 来源

《Claude Code 科研手记》第 10 章「并行 Agent」、§4.2「批量文献核查」