To Reference

---
name: to-reference
description: >
  把昇腾先验知识沉淀成 reference 词条。输入支持内联粘贴、单个文件、URL 爬取、或从已有 case 集合归纳共性。提取事实/方法论，按 references/_types.yaml 归类（error-code / tool / platform-fact / command-side-effect / methodology），标来源类型（official-doc / engineer-input / case-derived）与验证状态，经 grill 阶段与用户反复确认意图后，产出结构化 YAML 词条（status: active 直进正式 type 目录，PR review 即审核闸门——合入即生效）。这是先验知识的统一入口——与 to-postmortem（案例）并列，先验知识从这里汇入，不从 diagnose 自动生成。
---

# To Reference

先验知识注入入口，与案例知识（`/skill:to-postmortem`）并列。**reference 是独立于任何具体事故的领域事实与方法论**——不是 case，不携带 symptoms/diagnosis/fix 闭环。本 skill 的产物以 `status: active` 直接落入正式 type 目录（`references/<type-dir>/`），**PR review 即审核闸门——合入即生效**：词条随 PR 提交，review 通过合入 = active 进入诊断上下文。未合入的 PR 分支不 main，天然不进诊断上下文——安全性语义由"合入动作"承担，不再需要 draft 中间态隔离。

> ⚠️ **质量原则（比 case 更严）**：reference 是知识库的浓缩资产，一旦错误，污染的是所有引用它的诊断。**本 skill 的产出不是"录进去"，是"提交审核"**——先与用户反复确认意图（grill），再产出 active 词条随 PR 提交，由 maintainer 在 PR review 审核。环节缺一不可。

## 输入方式

接受四种输入，来源类型决定信任基础与后续审核深度：

**1. 内联粘贴**（工程师经验 / 手册片段，`engineer-input`）：

```
/skill:to-reference "在 A2 上排查通信问题，别查 HCCL_BUFFSIZE，查 NPU 驱动版本：cat /proc/driver/npu/version，期望 >= 23.0"
```

**2. 单个文件路径**（来源类型由 `--source` 指定，不默认绑定）：

```
/skill:to-reference --file ~/notes/npu-smi-fields.md --source engineer-input
/skill:to-reference --file ~/ascend/昇腾950_NPU架构白皮书.md --source official-doc
```

`--source` 是**必填判断项**（engineer-input / official-doc）：来源类型由**内容权威性**决定，不由输入通道决定——同一份文件可能是工程师笔记（engineer-input）也可能是官方文档（official-doc）。本地 PDF 用工具提取文本（如 `pymupdf`）后再走本模式；`.docx`/`.doc`/`.pptx`/`.xlsx`/`.rtf`/`.epub` 先转 Markdown（见 §1「二进制文档与截图」）。`verification` 状态见 §1。

**3. URL 爬取**（官方文档，`official-doc`）：

```
/skill:to-reference --ingest https://www.hiascend.com/document/.../plog-error-codes
```

**4. 从 case 集合归纳**（`case-derived`，最常见——工程师没有专门写先验知识的习惯，但案例里反复出现共性）：

```
/skill:to-reference --ingest-cases "[VLLM-ASC-9596, VLLM-ASC-12989, VLLM-ASC-9507]"
```

**5. 修订已有 reference**（`--update <ref-id>`——内容有误/过时/不完整时更新，**不是新增**）：

```
/skill:to-reference --update cann-runtime-error-codes --ingest <新来源 url>
```

- agent 读现有词条 + 新材料，产出**修订 diff 建议**（改了什么/为什么），人确认后落 PR；
- 修订 active 内容 = 修改已生效知识 → **kb/high-risk 双签**（对齐 case 层 knowledge_modification）；
- 修订前先确认该 ref 已被标 `pending-review` 或 `draft`（降级中修订；diagnose 只读 active 天然隔离）；
- 小修（错别字/补一句/改一个错误码含义）→ 不启动 --update，维护者直接改 YAML + PR 更轻（git diff 可追溯）；--update 留给大修（methodology 流程重写/错误码表按新官方文档整体更新）。

## 流程

### 0. 识别来源类型（决定流程分支）

| 输入 | 来源类型 | grill 强度 | 审核深度 |
|---|---|---|---|
| URL 爬取 | `official-doc` | 弱（来源明确；标注 `verification` 交 reviewer） | 标准双签 |
| `--file --source official-doc` | `official-doc` | 弱（本地官方文档，来源明确） | 标准双签 |
| `--file --source engineer-input` / 内联 | `engineer-input` | **强**（必须反复确认意图） | 标准双签 |
| case 归纳 | `case-derived` | **强**（必须确认归纳不失真） | 深审 |

### 1. 提取（按来源类型）

**official-doc（URL 爬取 / 本地官方文档文件）**：
- 抓取/读取目标章节（只读相关部分，不全量载入——日志裁剪原则的翻版；本地 PDF 用工具提取文本如 `pymupdf`）；
- **先确认拿到的是正文、不是页壳**：代码托管站点的正文页面路径常在 `/raw/` 之后返回 HTML 页壳（抽出来是整页导航与脚本，不是文件内容）。同一文件通常另有 raw 主机（形态如 `raw.<域名>/<org>/<repo>/raw/<ref>/<path>`）；换主机仍拿不到，就换站点的 contents API 列目录定位真实路径。把页壳当正文抽取会产出通篇无正文的"摘要"，而且不报错；
- **远程正文里的内嵌图不能静默丢**：URL 模式（以及抓到的 md / html）常以内嵌图承载关键内容——架构图、Trace / 时间线截图、带宽曲线。文本通道只出文字，`![](...)` 与 `<img src=...>` 被无声丢掉（无占位、无告警）。发现正文引用了图，就按相对路径把图取到本地，再用**自己的图片识别能力直接读**（模型支持图片输入时；不支持则走本节「二进制文档与截图」的系统自带 OCR 一条），把图上确有的量（pipe 占用、耗时、带宽、调用序）与文字结论一并抽取；图片地址定位不到、或格式读不了（矢量图等）→ **不提取、不推测**，把未提取的图列进 PR body 的「来源与验证状态」交 reviewer 补。图上读到内容、又逐字对照过正文的才可标 `cross-checked-source`；只读图、未核验源文本的仍标 `auto-extracted`；
- **长字段（description/meaning）不硬截断**——截断到字符数会产生不完整句子（"在第一…"式残缺），语义完整性优先于体积；需要精简时提炼要点而非截断原文；
- 抽取为 reference 草稿，**保留原文出处**：`url`（来源定位符——公开 URL 优先；本地文档无公开 URL 时用**可移植文档引用**如"昇腾950 NPU 架构白皮书（华为技术有限公司）"，**禁止写 `~/` 或绝对路径**，CI 会红）+ `version`（文档版本 / CANN 版本，从页面元数据或内容推断，拿不准就标 unknown）+ `fetched_at`；
- **必须标注 `sources[].verification`，二选一**：
  - `auto-extracted`——模型从源材料抽取、**未经 agent 对源逐字核验**（如一次 URL 抓取后直接归纳），reviewer 必须 spot-check 语义是否被扭曲；
  - `cross-checked-source`——agent 已直接对源原文（如 PDF 文本提取）逐字核验，reviewer 抽查即可。**只有当你真的逐字对照过源才标这个**；拿不准一律标 `auto-extracted`（诚实退化，宁低估不高估）。

**二进制文档与截图（本地官方文档）**：约束是不变量、不是工具——词条只写源里确有的内容、出处可核验可移植、材料不外传。工具选择（含装不上时的替代路线）都在这个约束之下。
- **文本提取（首选）**：`.docx`/`.doc`/`.pptx`/`.xlsx`/`.rtf`/`.epub` 用 `npx -y @firecrawl/anydoc <file> -o <file>.md`（Node ≥ 20，首次自动下载，保留表格/公式）；无 Node 但有 Python ≥ 3.10 → `pip install firecrawl-anydoc` + `python -c "import anydoc,sys; print(anydoc.to_markdown(sys.argv[1]))" <file>`；PDF 用 `pymupdf`。
- **首选装不上就自己找路，别直接判失败**：这些格式本质是 zip + XML——`.docx` 读 `word/document.xml` 的 `<w:t>`；`.pptx` 读 `ppt/slides/slide*.xml`；`.xlsx` 读 `xl/sharedStrings.xml` + `xl/worksheets/sheet*.xml`；`.odt`/`.ods`/`.odp` 读 `content.xml`（`python -m zipfile -e <file> out/` 解包，Windows 无 Python 用 `[System.IO.Compression.ZipFile]::ExtractToDirectory`）。丢掉的表格/排版如实记进 PR body，不假装完整。探索出的新路线跑通了值得固化 → 交给收尾的伴随演进评估（见 `/skill:evolve-check`），**不要在这里自己加卡**。真的都抽不出来 → 请用户转成 md 或贴文本，**不静默跳过附件**。
- **截图**：纯文本通道（anydoc 或 XML 提取）只出文字，架构图 / 报错截图会被丢掉（anydoc 无占位、无告警）。`.docx`/`.pptx`/`.xlsx`/`.odt` 都是 zip，用 `python -m zipfile -e <file> out/` 取 `word/media/`（pptx 为 `ppt/media/`，xlsx 为 `xl/media/`），再用**自己的图片识别能力直接读图**（模型支持图片输入时；模型不支持则见下一条的系统自带 OCR）。
- **没有读图能力时，先用系统自带 OCR 兜一层，再判「不提取」**：模型不支持图片输入时（读图工具用不了），用**操作系统自带的 OCR** 取字：Windows 用 `Windows.Media.Ocr`（PowerShell 可调，中文需先装语言包）、macOS 用 Vision 框架（`VNRecognizeTextRequest`）或「实时文本」、Linux 已装 `tesseract` 就用它。OCR 是工具、不是模型判断，但**字准不保证**：数字与单位最易错（`0.5%` 与 `0.05`、`0.01` 与 `0.1` 这类阈值尤其），流程图箭头与连线走向基本会丢。所以 OCR 取到的**阈值与参数值必须在 grill 阶段逐项与提供者确认**，确认不下来就按「未提取」处理；`verification` 仍标 `auto-extracted`（未经逐字核验），并在 PR body 的「来源与验证状态」写明「来自 OCR、建议抽查」。
- **读图与 OCR 都走不通 → 不提取、不推测**：词条只写文本里确有的内容，未提取的截图列进 PR body 的「来源与验证状态」区块交 reviewer 补——**不要从截图的标题或上下文反推内容**。
- **确定性提取才可逐字核验**：anydoc 或 XML 直读都是确定性解析（不经模型改写），逐字对照原文后可标 `cross-checked-source`；未逐字对照的仍标 `auto-extracted`。
- **出处仍须可移植**：本地 docx 的 `sources[].url` 用可移植文档引用（标题 + 出品方 + 版本），**禁止写 `~/` 或绝对路径**（CI 会红）。
- **不外传**：不要用 `--ocr hosted`（把整份文档上传第三方服务）；内部文档一律本地处理。

**内联 / 文件（engineer-input）**：
- 从工程师描述中抽取事实/方法论，判断 type（见 §2）；
- 判断它**独立于具体事故**（是 reference）还是**绑定事故**（是 case，引导走 `/skill:to-postmortem`）；
- 缺失的信息（适用平台？适用版本？出处？）记下来，grill 阶段逐项问。
- **来源身份按可公开化要求处理**：`engineer` 承载**来源描述**，不必是真实姓名——材料要求匿名（不带部门与人名）时写角色化的来源描述（如「RL 精度调优经验分享（提供者匿名）」），真实身份留在会话侧不入库；来源文档的标题与形态写进 `sources[].document`（无公开 URL 时由它承载出处）。非公开链接、部门名与人名一律不写进词条——出处要可核验，但不以暴露未公开信息为代价。

**case 归纳（case-derived）**：
- 读取指定 case 的 `root_cause` / `diagnosis` / `fix`；
- 找**共性模式**——重复出现的根因对象、相似的诊断步骤、相似的 fix 模板；
- 归纳为 reference 草稿，**保留证据**：`cases: [<case-id>, ...]` + `extracted_at`；
- 区分两类产物：事实共性 → `platform-fact`/`error-code`/`tool`；流程共性 → `methodology`。

### 2. 归类（type 判定）

按 `references/_types.yaml` 注册表判定 type：

| 信号 | type |
|---|---|
| 错误码/异常代码的含义 | `error-code`（**表形态**——按组件分族成表，一个族一个文件；多个码合入同一表，不逐码建文件） |
| 工具/命令的用法与输出解读 | `tool` |
| 平台硬事实（可独立验证的客观事实） | `platform-fact` |
| 软件栈/运行时系统硬事实（日志路径与格式、机制、进程行为；不绑定硬件平台） | `software-fact` |
| 故障模式对照（现象→根因→处理，按主题域成表） | `fault-pattern`（**表形态**——一个域一个文件，条目 `pattern/symptoms/cause/fix`） |
| 命令/环境变量的副作用与回滚 | `command-side-effect` |
| 多步骤诊断/调优流程 | `methodology` |

区分 `platform-fact` 与 `software-fact`：绑定具体硬件平台/芯片规格（如 "A5 HBM 64GB"）→ `platform-fact`；CANN 软件栈或运行时系统的可验证事实（如日志路径、格式、机制，跨平台成立）→ `software-fact`。

**fault-pattern 表形态（组织单元 = 验证单元）**：官方手册的"现象→根因→处理"排障条目（非多步流程、非事故闭环）→ 按主题域成表（如 `references/fault-patterns/dvpp-decode.yaml` 承载 VDEC/JPEGD 解码故障）。`symptoms` 是可直接 grep 的日志签名/错误码（诊断时按签名命中根因），`cause`/`fix` 提炼自来源。

**error-code 表形态（组织单元 = 验证单元）**：错误码天然成族（CANN Runtime 507xxx / HCCL / aicpu / Driver），同族同源同验证——**一个族一个文件**（如 `references/errors/cann-runtime.yaml` 承载 507903/507018/507057...），表级共享 sources/status/applies_to，不逐码建文件。case 提炼的条目逐条验证 → 条目带可选 `source_cases`。检索时 agent 按族定位文件，表内 grep code 一次命中。**数据集类的 `applies_to` 平台/版本应从来源的结构化字段映射（如官方文档的 models/support 字段），不靠 agent 猜测**——来源没声明的平台不写。

**tool 组织单元 = 一个「诊断用途面」**（不是「一个可执行文件」，也不是「一个子命令」）——先查 `references/tools/` 是否已有同用途面条目，有则**追加到该条目的 `content.commands`，不新建文件**。判据三问的实质：**它们是不是一次动作的三个面（配置/执行/输出）**——是则合，是两个独立动作则拆。三问：①**同验证**（同版本 pin + 同次 `last_verified`，可以是同一份文档，也可以是一份能力的配置面+执行面文档）；②**同诊断**（一次诊断会同时需要它们——同 category、同阶段）；③**同动作**（同一动作的三个面，各有自己的命令与输出面即为两个动作）。反例：一个产品有 20 个子命令 ≠ 20 个词条——按用途面归并（msprobe 的 dump+config.json 是「采集」这一次动作的配置面与执行面 → 合；compare 与 graph_visualize 是两个独立动作、两套输出语义 → 拆）。**检索键前置**：工具名 / 子命令名必须出现在 `title` / `summary` 开头——`tool` 走 summary 层（`_summary-index.yaml`）且该层会截断，键写在后面等于检索不到。

拿不准 type → 按最贴近的登记 type 落草稿，并在草稿里标注 `type_uncertain: true` 交 maintainer 定夺。**不要自行发明未登记 type**（CI 会红；登记是 maintainer 的动作，见 `_types.yaml`）。

### 3. Grill 阶段（关键——确保产物符合用户意图）

**工程师输入（内联/文件）必须逐项确认，不是一次性"对吗"**：

1. **意图确认**：把你提取的核心事实/方法论用自己的话复述给用户："我理解你说的是：……，对吗？"——用户纠正就更新，直到用户明确认可；
2. **边界确认**：适用平台？适用框架/版本？适用范围之外的情况是不是也成立？逐维问（platforms / frameworks / versions / categories），确认 `applies_to` 字段；
3. **出处确认**："这条经验的来源是？——某次客户案例 / 某份内部文档 / 官方手册哪一章？"出处含糊 → 草稿标 `source_vague: true`，仍可进 inbox 但 maintainer 审时会重点查；
4. **排除确认**："这条在什么情况下**不**成立？"——工程师最常漏掉反例，这是 reference 区别于 case 的关键（reference 是断言，必须有适用范围）。

**case 归纳必须确认不失真**：

1. **共性确认**："这三条 case 的共同点是 X，我归纳为 Y，对吗？"——用户认可才继续；
2. **差异确认**："这三条里有没有哪条是特例（根因不同但现象相似）？"——有特例就剔出，避免把偶然共性当规律；
3. **覆盖确认**："这个归纳覆盖了你要沉淀的东西吗？还是你心里还有第 4 种场景？"

**official-doc**：不逐项 grill（来源明确），但**必须在报告里显式告诉用户验证状态**——`auto-extracted` 要说明"这是模型抽取的摘要，建议打开原文核对语义"；`cross-checked-source` 要说明"已对源原文核验，可抽查"。把 `verification` 写进草稿 `sources[]`。

**grill 分级（体验瘦身——反复对齐是置信度增加过程，但按需分级，不是无差别多轮）**：

- **高置信（默认）**：来源明确（official-doc）、内容自包含、无歧义 → **单次确认**——一次复述"我理解你说的是：……，对吗？"，用户认可即过，不逐项追问；
- **中置信**：工程师输入但表述清晰 → 确认意图 + 出处，边界/反例顺带一问；
- **低置信**（必须多轮）：表述含糊、来源不明、边界不清 → 完整四轮（意图/边界/出处/反例）逐项确认。

判据：**agent 自评置信度决定 grill 深度**——高置信单次、低置信多轮；拿不准往高一档走（宁可多确认一次，不因省事产出歧义词条）。

grill 是**人审的第一道过滤**——确认过程中用户放弃/否认的条目，直接丢弃，不进 inbox。宁可少而准，不要多而疑。

### 4. 去重与聚类归属检查（进正式目录前）

扫 `references/` 现有词条，分三种关系：

- **完全覆盖**（现有词条已含本条全部内容）→ **不产草稿**，告诉用户"这条已被 `<ref-id>` 覆盖"，列出比对；
- **变体**（同主题不同平台/版本）→ 提示用户："现有 `<ref-id>` 覆盖 A3，你这条是 A5 场景——是要并进现有词条的 applies_to，还是独立词条？"按用户回答处理；
- **层级**（现有词条是总览、本条是细节，或反之——如现有 `a5-l2-cache` 总览 vs 本条 `a5-l2-cache-detail`）→ 提示用户："现有 `<ref-id>` 是总览，你这条是同一主题的细节——建议独立词条并在两边 `related_references` 互指；或并进现有词条。哪种？"按用户回答处理。层级关系本身是**合法结构**（不是重复），但要显式互链，避免检索时只见其一；
- 查不到 → 新词条，继续。

**聚类归属（追加不新建）**——数据集类（error-code）在去重之外还要判定族归属：

- 提炼到错误码 → **先查 `references/errors/` 现有文件**，按组件判定归属（族划分跟随来源——CANN 错误码参考怎么分章，文件就怎么建）；
- 归属已有族（如 507xxx 进 `cann-runtime.yaml`）→ **追加到该表 `errors` 列表**，标新 `source_cases`——**不新建文件**；
- 仅无对应族文件时才新建（如第一个 HCCL 错误码 → 建 `references/errors/hccl.yaml`）；
- 独立词条类：查 `tags` / `related_references` 是否可关联现有词条，**不合并**（关联不合并——主题聚合由标签承担，不是文件合并）。

### 5. 产出词条 → `references/<type-dir>/`（active，无 _inbox）

> ⚠️ **词条零注释（硬规则）**：下面模板中的 `#` 注释是**给作者看的写作指引**，产出 YAML 时必须**删除全部注释行**——词条是给 agent 消费的数据，不是带元说明的文档；重复注释是 token 浪费（23 条 × 同一注释的教训）。语义解释（url 定位符规则、verification 含义、status 规则、字段含义）只存在于 SKILL.md / references/README.md 文档层，**不进词条**。值自解释就不加注释。

按 reference schema 产出完整 YAML（字段定义见 `references/_types.yaml` 与 `references/README.md`；基础元信息 + content 全部填齐，CI 强校验——词条必须 schema 完整，这是与 to-postmortem 草稿可残缺的差异）：

**写词条时的行文**：reference 词条是给人检索、给 agent 载入的文本，按 `docs/spec/writing-norms.md` 写（可选论证层，不影响本 skill 执行）；本面的定制条款见该文件 §3 的「case / reference 词条」一行——症状句要能直接当 grep 判据（保留报错原文与算子名），事实与结论直接写，不写推理过程。

```yaml
id: <kebab-case-slug>              # 唯一；如 plog-error-507903、a3-hccl-buffsize-check
type: <registered-type>            # 见 references/_types.yaml
title: <short>
summary: <one-liner>

sources:
  - type: <official-doc | engineer-input | case-derived>
    # official-doc: url + version + fetched_at [+ verification]
    # engineer-input: engineer + input_session + confirmed_at [+ document]
    # case-derived: cases + extracted_at
    # verification（official-doc 必填，其余可选）:
    #   auto-extracted | cross-checked-source

applies_to:                        # 能确定就填，确定不了留待 grill 后补
  platforms: [...]                 # A2-910B | A3-910C | A5-950 | cross
  frameworks: [...]
  versions: {...}
  categories: [...]                # methodology 必填

status: active                      # 产出即 active——PR review 即审核闸门，合入即生效
last_verified: <今天>              # 人确认的日期（grill 认可即视为一次人核）
# 观测字段（可选；产出时**不填**，由 groom 在 reference 观测回写时有数据才填）：
#   hits: <int>                    # 被引用次数（trace.reference_lookup 计数）
#   last_hit: <date>               # 最后引用时间

content:
  # 按 type 的 schema_required 字段（见 _types.yaml / references/README.md）
  # error-code 是表形态：content.errors 列表，一个族一个文件，不逐码建文件
  #   errors:
  #     - code: "507903"
  #       meaning: "..."
  #       related_signatures: [...]
  #       source_cases: [<case-id>]   # case 提炼的证据（可选）
```

- `status` **写 `active`**——产出即 active，PR review 即审核闸门，合入即生效；**深审条件在产出时就满足**（case-derived + methodology 需 ≥3 条 case 引用，CI 强校验，产出时不达标 PR 直接红——不允许以 active 提交未达深审门槛的词条）。未合入的 PR 分支不 main，天然不进诊断上下文；合入动作即审核通过；
- 初始 confidence 按来源类型（写进词条注释，供审核参考）：`official-doc` 0.6 / `engineer-input` 0.3 / `case-derived` 0.3–0.6（case 数与一致性越高越靠近 0.6）；
- `last_verified` 填今天——grill 阶段用户认可即视为一次人工确认，但**这不替代 maintainer 审核**；
- **产出前检查：词条文件里不得有任何 `#` 注释行**（上模板中的注释全部删掉）——`grep -c "#" <file>` 应为 0。

### 6. 报告落点（生成后必须明确告知）

```
词条 → references/<type-dir>/<ref-id>.yaml（status: active）
来源类型：<engineer-input | official-doc | case-derived>
状态：active（PR review 即审核闸门——本词条随 PR 提交，合入即进入诊断上下文；case-derived + methodology 已按 ≥3 条 case 引用满足深审门槛）
审核建议：<按来源类型的审核深度提示>
```

别让用户去找自己的产出——报出具体路径，说明"随 PR 提交，review 合入即生效"。

### 7. 收尾 evolve-check（伴随演进评估，默认执行）

**先落执行记录**（evolve-check 读它作现场）：
`python3 scripts/log_skill_exec.py --skill to-reference --products "<ref-id>(active),..." --reason "<一句话：归纳 N case / 新增家族>" --source <来源> --tokens <估算>`

词条产出、出最终报告前，执行一次伴随演进评估（`read skills/evolve-check/SKILL.md`
遵循）：本轮发现可跨词条归纳的共性（T1）、新错误码家族首次入表需扩覆盖（T5）、
或提取/归类环节有流程摩擦（T3/T4）时，**agent 自动产 idea 卡并自行验证执行**
（ev_proposal 产卡 → 验证 → 进攒批）；无信号则报告加一行"evolve-check：无演进
信号"。这是流程默认收尾，**不需要用户另说"改进系统"**——演进由数据触发，像人
学习。产出与流程报告一并给出。

## 产出落点

- `references/<type-dir>/<ref-id>.yaml`——词条（status: active；PR review 即审核闸门，合入即生效，无中间 draft 态）
- PR review：reject → 不合并（分支废弃，词条不进 main）；request changes → 修改后重新提交；approve + 合入 → active 生效
- 遗留 draft（历史旧态，修订 3 前产出）：由 `/skill:knowledge-groom` R1 按需清理或补审

**与 to-postmortem 的分工**：案例（事故闭环）→ `/skill:to-postmortem` → `knowledge/`；先验知识（独立事实/方法论）→ `/skill:to-reference` → `references/`。两条入口不互相覆盖——to-postmortem 不自动产 reference，to-reference 不反向产 case。

## 为什么先验知识要专门入口

案例沉淀（to-postmortem）解决"同类问题下次直接命中"；但工程师的**通用经验**（怎么查 plog、哪个命令看什么、这个错误码意味着什么）不绑定任何具体事故，散在个人脑子里，每次诊断都重新摸索。没有专门入口，这些知识永远进不了仓库——因为工程师不会为了沉淀"我知道怎么查设备日志"去写一份 postmortem。to-reference 把这个门槛降下来：**工程师随口一句话，agent 提取 + grill 确认，30 秒产出可提交词条**。