---
name: failbook
description: The internet's mistake notebook — when a task failed twice, search real cases of similar failures before the 3rd attempt; the cause is usually in the request, not the model.
---

# failbook

模型连错两次,第三次尝试前先查 failbook:检索真实世界里「相似提问场景」的失败案例。两连败通常说明任务描述/流程里有一个隐含假设错了——案例库告诉你别人错在哪、怎么改问法。只收「人错型」案例(模型升级不会让案例过期),不收模型 bug 型。

## 动线(何时调用)

1. 同一任务失败第 2 次后、**第 3 次尝试前**:用当前任务描述跑 `search`
2. 把命中案例的「典型提问 / 根因 / 建议改问法」**展示给用户确认**:「你是不是其实想……」
3. 用户确认后,按 `rephrased_request` 的方式重新陈述任务再试
4. 问题解决且案例库无此案例时,提议贡献新案例(见仓库 README 的 PR 流程)

## 安装

```bash
# 源码运行(Node 18+,零依赖)
node bin/failbook.js <command>

# 或链接成全局命令
npm link
failbook <command>
```

作为 skill 安装:把本目录(SKILL.md + bin/ + src/ + locales/ + cases/)拷入你的 skills 目录;cases/ 是随包案例快照,更新用 `git pull` 或重新下载。

## 命令清单

| 命令 | 说明 |
| --- | --- |
| `search <query...>` | 检索相似失败案例(两连败后第三次尝试前运行) |
| `validate [--cases D]` | 校验案例库格式(贡献前自检) |
| `help` | 显示帮助 |

search 选项:`--limit N`(默认 3)、`--json`(机器可读)、`--category C`(限定分类)、`--cases DIR`(外部案例库)。
全局选项:`--lang zh|en`(默认 en)。

## 典型调用示例

```bash
# 两连败后,第三次尝试前:
failbook search "build passes but the site still shows old content after deploy"

# 给用户确认用的机器可读输出:
failbook search "exit code 0 but build failed" --json --limit 2

# 限定分类:
failbook search "coordinates click wrong window" --category automation

# 贡献案例前自检:
failbook validate
```

## 输出约定

`search` 的每条结果含:症状、典型提问(`question_pattern`,检索键)、建议改问法(`fix.rephrased_request`)。**必须让用户确认后再按新问法重试**,不要静默替用户改任务。