# 判断回溯录（ERR-XXX，原「踩坑错误册」）

> 任务结束后触发"新坑即录"：凡本轮新踩/复现且解决耗时 ≥ 40min 的坑，强制性在索引新增一行 + 建立独立 .md。

本 reference 收口于 Step 6 复盘沉淀阶段。

**定位升级**：本册不只记"坑的结果"（根因/修复/防范）来省时间，更要把每一条变成**决策失败样本**——记录"当时基于什么证据判错、正确判据应是什么、为什么没想到那个信号"，让诊断从"查关键词命中"升级为"见过这种错判长什么样"的模式匹配。

---

## 索引模板

文件：`{PROJECT_ROOT}/.ai-memory/error_index.md`

```markdown
# 错误索引

| ERR-ID | 一句话描述 | 根因分类 | 触发关键词 | 新增日期 | Recurrence-Count |
| ----------- | -------------------------- | ------------ | ----------------------------------------- | ---------- | ---------------- |
| ERR-001 | 帝国CMS路由表有值但加载失败 | 框架行为假设 | 路由表有值, 不会加载 | 2026-07-11 | 1 |
| ERR-002 | 中文路径致Python安装失败 | 平台差异 | 用户名非英文, 安装失败 | 2026-07-12 | 1 |
| ERR-003 | write_file时间戳副本未覆盖 | 工具行为 | 覆盖, rename-item, 时间戳副本 | 2026-07-20 | 1 |
| ERR-004 | 环检测递归三次都判错环数 | 算法正确性 | 环检测, 递归, 回边, cycle | 2026-08-14 | 1 |
| ERR-005 | 为简单校验过度抽象出策略模式 | 设计取舍(taste) | 过度设计, 抽象, 策略模式 | 2026-08-14 | 1 |
| ERR-006 | build_graph 注释伪符号致假边 | 算法正确性 | 注释伪符号, 假边, strip_php_comments, phantom | 2026-08-14 | 1 |
```

**分类标准（共十类）**：框架行为假设 / 平台差异 / 配置冲突 / 缓存/竞态 / 工具行为 / 业务逻辑 / 安全沙箱 / 环境变量 / **算法正确性** / **设计取舍(taste)**。

- **算法正确性**：环检测 / 图遍历 / 递归 / 状态机 / 排序等"跑通但结果错"类缺陷（如环检测三次没写对）。此前此类坑进不了册子，属分类缺口，必须单独归类。
- **设计取舍(taste)**：取舍权衡判断失误（过度设计 vs 简化、抽象边界、API 形态、是否引入依赖等），属审美/判断力层面而非纯技术错误。

---

## 单条模板

文件：`{PROJECT_ROOT}/.ai-memory/errors/ERR-XXX.md`

```markdown
# ERR-XXX: {错误一句话描述}

- **根因分类**：
- **触发条件**：
- **排查路径**：
- **错判点**：（当时基于什么证据判错了——误信了哪个信号、忽略了哪个反例）
- **正确判据**：（应该用什么信号才对——可证伪的判定标准）
- **盲区**：（为什么之前没想到这个信号——认知/经验缺口，而非技术盲区）
- **修复方式（可复用）**：
- **防范措施**：
- **规避方案**：
- **关联知识库**：（列出相关技术或工具的官方文档关键词 / sector）
- **来源会话**：（可选，标记首次发生的会话 ID 或日期）
- **Recurrence-Count**：1（复现次数，capture_learning.py 去重提示驱动累加）
- **First-Seen**：（YYYY-MM-DD，首次发生日期）
- **Last-Seen**：（YYYY-MM-DD，最近复现日期）
- **Tasks**：1（跨不同任务数，Recurrence>=3 且 Tasks>=2 触发 promote 建议）
- **Pattern-Key**：（可选，稳定去重键，如 cms.routing.table_loaded）
```

> 上方 4 个 Recurrence 字段由 capture_learning.py / recurrence_promote.py（学习捕获 hook 草案）消费：
> 单条含此字段时，recurrence_promote.py 可评估硬规则（Recurrence-Count>=3 且 Tasks>=2 且 30 天窗口）并输出 promote 建议；缺字段则优雅跳过。

禁止字段：本模板仅含技术信息。禁止记录密码 / Token / API Key / SSH Key / 账号凭证 / 生产 IP / 内部域名。

---

## 触发与读取

### 诊断阶段触发

在 Bug 诊断 / 代码审查 / PHP 内联 JS 等 session 中，Agent 优先按**错判形状**做模式匹配，而非只查触发关键词：

- 先匹配 `error_index.md` 行的触发关键词，命中后读 `errors/{ERR-ID}.md` 全文
- 重点比对单条中的 **错判点 / 正确判据 / 盲区**：当前是否落入同样的"误信信号、忽略反例"模式
- 若当前症状与记录匹配 → 优先复用修复方式与正确判据，并对本结论先跑证伪门禁，计时从 0 开始
- 若相似但不完全匹配 → 标记为变体，修复后新建 ERR-ID（不覆盖原条目），并在新条目的错判点中说明与旧条目的差异

### 新坑即录

任一 session 中踩的新坑且排查耗时超过 40 分钟（从初步定位到 fix 完成），强制性操作：

1. 分配下一个可用的 ERR-ID（如 ERR-004）
2. 按单条模板创建 `errors/{ERR-ID}.md`
3. 在索引表追加一行
4. 同步更新 `project_memory.md` 中的 Known Issues 节（写缩写引用：`参见 ERR-XXX`）
5. 运行 `python hooks/recurrence_promote.py` 评估本条目及全量错误是否满足升规则硬条件（Recurrence-Count≥3 且 Tasks≥2 且 30 天窗口），满足则输出 promote 建议交用户确认（不自动改写规则文件）

> **排查时间估算**：从首次发现症状到修复方案确认，按 Agent 与用户交互轮次×平均轮耗时估算；≥ 4 轮交互视为接近 40 分钟阈值，建议记录。

---

## 归档策略

- 索引表超过 50 行时触发归档提醒：`⚠️ 错误索引已超 50 条（当前 X 条），建议将 3 个月前的旧条目归档至 archive/error_index_{YYYY}.md`
- 单条 ERR-XXX.md 超过 500 行时触发拆分提醒
- 合并规则：连续 3 个 ERR-ID 同一根因 → 合并为一条，保留各变体修复方式

---

## 禁忌

- 不记录密码 / Token / API Key / 凭据 / 生产 IP
- 不经确认不写入
- 不跨项目复用（每项目独立索引）