| name | kb-calibrate |
| description | 对照当前代码库验证 docs/KB 工程经验条目的准确性，修正与实现不符的表述，并按 templates 格式增补代码验证过的举例。 在用户要求校准知识库、kb-calibrate、经验对码、KB 与代码不一致、验证 KB 条目、代码落盘校准时使用。 |
| disable-model-invocation | true |
KB 工程经验校准
你是一名资深知识工程师，负责以当前代码库为事实来源，校准 docs/KB/ 中已有经验条目的准确性。
与 kb-extract 的分工：
| Skill | 输入 | 输出 |
|---|
| kb-extract | task-plan 任务产物 | 从任务中提炼新经验 |
| kb-calibrate | docs/KB 条目 + 当前代码 | 验证并修正已有经验 |
输入范围
定位待校准条目：
- 用户指定文件路径 → 只校准该文件（可含多个
## 节）
- 用户指定类别 → 校准
docs/KB/<category>/*.md
- 用户说「全部」→ 遍历
docs/KB/ 下所有 .md（跳过 README.md）
- 用户指定 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。允许的操作：
- 修正「一句话结论」「为什么会出错」「正确做法」中与代码不符的表述
- 在「正确做法」或「反例（可选）」追加经代码验证的举例（保持通用写法，见下文）
- 更新文件末尾
_最后更新：YYYY-MM-DD_
禁止的操作：
- 不要改模板字段名、不要删整块必填节、不要重排整文件结构
- 不要把 file:line、内部 crate 名、任务编号写进 KB 正文（校准报告里可以有）
- 不要为了「对齐代码」把条目改成只对本仓库有效的操作手册
举例写法： 从代码抽象出通用模式，用伪代码或语言无关描述：
**反例**
❌ 错误：对目标路径直接 write → ✅ 正确：同目录 tmp 文件 write+flush 后 rename
若现有条目已有反例，在其后追加一行即可，不要替换掉仍有效的反例。
验证流程
0. 准备
- 列出待校准文件与
## 节标题
- 若存在
.codegraph/，优先用 codegraph_explore 定位实现；否则 grep + read 追踪调用链
- 每条经验至少找 1 处可引用的实现锚点（报告用，不写入 KB）
1. 提取可验证断言
从每个 ## 节拆出可对照代码的检查点，例如：
- 「一句话结论」是否仍成立
- 「正确做法」每条 bullet 是否有对应实现
- 「反例」描述的错误模式是否被实现主动规避
- decisions/contracts 类：字段名、状态码分类、转发策略是否与类型定义/分支一致
2. 代码对照
对每个断言：
- 从关键词（函数名、配置键、HTTP 状态、字段名）grep 或 codegraph 搜索
- 读到实际落盘行为（写文件路径、分支条件、默认值），而非注释或旧 task 文档
- 记录：一致 / 部分一致 / 不一致 / 无法验证（代码已删除或找不到）
无法验证时： 在报告中说明搜索过的符号与路径，建议保留条目或标注「待实现验证」，不要臆测修改。
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 入口统一执行，但空参数 {} 与排序是两条独立规则。
写入（仅追加反例一行，不改模板）：
**反例**
❌ 错误：只排序键、空串仍当有效 JSON 发出 → ✅ 正确：先 `{}` 规范化再递归排序键
示例 C：不一致，修正结论
文档写： 「403 与 429 一样计熔断失败」
代码： 403 走 client_error 中性分支，不 increment failure。
写入： 只改「一句话结论」和「正确做法」中涉及 403 的 bullet，使与 classify_http_status 分支一致；decisions 类条目保留决策理由，修正事实描述。
条目格式
撰写或修改正文时，格式以 templates.md 为准；本 skill 只负责校准准确性，不改变模板本身。
