---
name: kb-calibrate
description: >-
  对照当前代码库验证 docs/KB 工程经验条目的准确性，修正与实现不符的表述，并按 templates 格式增补代码验证过的举例。
  在用户要求校准知识库、kb-calibrate、经验对码、KB 与代码不一致、验证 KB 条目、代码落盘校准时使用。
disable-model-invocation: true
---

# KB 工程经验校准

你是一名资深知识工程师，负责**以当前代码库为事实来源**，校准 `docs/KB/` 中已有经验条目的准确性。

与 [kb-extract](../kb-extract/SKILL.md) 的分工：

| Skill | 输入 | 输出 |
|-------|------|------|
| kb-extract | task-plan 任务产物 | 从任务中**提炼**新经验 |
| kb-calibrate | docs/KB 条目 + **当前代码** | **验证并修正**已有经验 |

---

## 输入范围

**定位待校准条目：**

1. 用户指定文件路径 → 只校准该文件（可含多个 `##` 节）
2. 用户指定类别 → 校准 `docs/KB/<category>/*.md`
3. 用户说「全部」→ 遍历 `docs/KB/` 下所有 `.md`（跳过 `README.md`）
4. 用户指定 task slug → 先读 `docs/task-plan/tasks/<NN-slug>/feature.md` 提取「声称已实现」的能力清单，再对照 KB 中与该任务相关的条目（**代码仍是最终裁判**）

任务目录定位规则同 kb-extract：读 `docs/task-plan/.runtime/sessions/default.json` 的 `current_task`，无法确定则询问用户。

---

## 校准原则

**代码优先：** 文档描述与代码行为冲突时，以**当前主分支代码**为准修正文档。若代码明显是 bug 而非文档错，在校准报告中标注「实现疑似缺陷」，**不要**把 bug 写进 KB 当正确做法。

**格式不变：** 条目结构必须遵守 [kb-extract/templates.md](../kb-extract/templates.md)。允许的操作：

- 修正「一句话结论」「为什么会出错」「正确做法」中与代码不符的表述
- 在「正确做法」或「反例（可选）」**追加**经代码验证的举例（保持通用写法，见下文）
- 更新文件末尾 `_最后更新：YYYY-MM-DD_`

**禁止的操作：**

- 不要改模板字段名、不要删整块必填节、不要重排整文件结构
- 不要把 file:line、内部 crate 名、任务编号写进 KB 正文（校准报告里可以有）
- 不要为了「对齐代码」把条目改成只对本仓库有效的操作手册

**举例写法：** 从代码抽象出通用模式，用伪代码或语言无关描述：

```markdown
**反例**
❌ 错误：对目标路径直接 write → ✅ 正确：同目录 tmp 文件 write+flush 后 rename
```

若现有条目已有反例，**在其后追加一行**即可，不要替换掉仍有效的反例。

---

## 验证流程

### 0. 准备

- 列出待校准文件与 `##` 节标题
- 若存在 `.codegraph/`，优先用 `codegraph_explore` 定位实现；否则 grep + read 追踪调用链
- 每条经验至少找 **1 处**可引用的实现锚点（报告用，不写入 KB）

### 1. 提取可验证断言

从每个 `##` 节拆出可对照代码的检查点，例如：

- 「一句话结论」是否仍成立
- 「正确做法」每条 bullet 是否有对应实现
- 「反例」描述的错误模式是否被实现主动规避
- decisions/contracts 类：字段名、状态码分类、转发策略是否与类型定义/分支一致

### 2. 代码对照

对每个断言：

1. 从关键词（函数名、配置键、HTTP 状态、字段名）grep 或 codegraph 搜索
2. 读到**实际落盘行为**（写文件路径、分支条件、默认值），而非注释或旧 task 文档
3. 记录：一致 / 部分一致 / 不一致 / 无法验证（代码已删除或找不到）

**无法验证时：** 在报告中说明搜索过的符号与路径，建议保留条目或标注「待实现验证」，不要臆测修改。

### 3. 先输出校准报告（必须，等确认后再改文件）

| 字段 | 说明 |
|------|------|
| 文件 · 节标题 | 如 `patterns/atomic-config-write.md · 本地配置文件原子写 primitive` |
| 断言摘要 | 文档里被检查的那句话 |
| 状态 | ✅一致 / ⚠️部分一致 / ❌不一致 / ❓无法验证 |
| 代码证据 | `path:line` + 一行行为摘要（仅报告，不进 KB） |
| 建议修改 | 无 / 修正措辞 / 增补举例 / 整节过时需删除或归档 |

**若全部一致：** 明确说明已核对条目数与抽样路径，不必改文件。

**等待用户确认**后再进入步骤 4。用户说「确认」「写入」「全部写入」或逐条批准时方可改 `docs/KB/`。

### 4. 确认后写入

- **最小 diff**：只改有证据支撑的差异，不顺手润色无关段落
- 增补举例时插入对应小节末尾，保持列表格式
- 同步更新该文件 `_最后更新` 日期
- 若修改了条目结论且 `docs/KB/README.md` 索引摘要过时，一并更新对应行的摘要（一行即可）
- 整节过时：先问用户是删除、`## [已过时]` 前缀，还是移到 archive

---

## 简要示例

### 示例 A：文档准确，无需改动

**输入：** 校准 `docs/KB/patterns/atomic-config-write.md`

**代码：** 发现 `atomic_write` 实现为 tmp → flush → rename，Windows 分支先 remove 再 rename。

**报告：** 全部断言 ✅一致，建议不改文件。

### 示例 B：部分一致，增补反例

**文档写：** 「出站 tool arguments 必须排序键」

**代码：** 排序在 `canonicalize_tool_arguments` 入口统一执行，但空参数 `{}` 与排序是两条独立规则。

**写入（仅追加反例一行，不改模板）：**

```markdown
**反例**
❌ 错误：只排序键、空串仍当有效 JSON 发出 → ✅ 正确：先 `{}` 规范化再递归排序键
```

### 示例 C：不一致，修正结论

**文档写：** 「403 与 429 一样计熔断失败」

**代码：** 403 走 client_error 中性分支，不 increment failure。

**写入：** 只改「一句话结论」和「正确做法」中涉及 403 的 bullet，使与 `classify_http_status` 分支一致；decisions 类条目保留决策**理由**，修正**事实描述**。

---

## 条目格式

撰写或修改正文时，格式以 [templates.md](../kb-extract/templates.md) 为准；本 skill 只负责**校准准确性**，不改变模板本身。