Expert Audit

---
name: expert-audit
description: 站在使用者视角审查 expert-team 产出的专家资产：零上下文用户能否看懂照用、格式是否合规（R1–R7 / CR1–CR9 / INDEX），格式问题自动修复、可读性问题给修复路径。触发："核对专家团"、"审查专家资产"、"expert audit"，或 expert-team 产出后自动触发。
---

# 专家资产审查（使用者视角）

## AI 说明层

**目的**：expert-team 的资产由 AI 生成，生成者自检（Step 5/6）有天然盲区——格式都对，但内容可能"作者自己懂、别人看不懂"。本 skill 提供独立的、使用者视角的验收环节。

**功能**：双轨审查——轨道A 使用者冷读测试（能看懂吗/能照用吗，核心），轨道B 格式合规（结构清点 + R/CR 规则 + INDEX 格式）。产出 P0/P1/P2 分级报告；格式类问题自动修复，可读性问题给出修复路径。

**使用场景**：
- expert-team 创建 / 合并补全一个专家（或专题）完成后自动触发
- 用户说"核对专家团"、"审查专家资产"、"这个专家文档能看懂吗"
- 使用专家资产时反复看不懂，怀疑资产质量

## 核心判据

> **假设使用者是一个只拿到这份文档、完全没有代码上下文的用户——他能看得懂吗？能照着用吗？**

一切审查围绕这一句话。格式合规是底线，"看得懂、照着能用"才是目标：格式全对但冷读不过，仍判不合格。

## 与相邻 skill 的边界

| skill | 关系 |
|---|---|
| expert-team | 生成资产并做**生成者自检**（R/CR 自查 + auto-review）；本 skill 是独立的**使用者视角事后验收**。内容级问题的重建/补全走 expert-team。项目全局资产 `PROJECT.md` 由 expert-team 维护，本 skill **默认不审查**，仅用户显式声明时审查 |
| expert-lookup | 查找复用资产；契约层小范围内容修正走其"受限增量更新"。本 skill 报告中的契约层 P0/P1 修复路径多指向它 |
| challenger | 通用对抗质疑，不了解专家资产结构；本 skill 是领域专项审查，内置资产结构与规则知识 |
| auto-review | 写文件后的通用质量闭环；本 skill 审查的是**已落盘的存量资产**，不依赖写入动作触发 |

## 输入与范围

- **默认单专家**：用户指定专家名（或从上下文推断，如 expert-team 刚完成的专家）；含子专家时一并审查
- **专题**：指定专题名时，审查专题层（topic.md / T0 / T1）+ 其下全部专家
- **全量**：用户说"全部核对一遍"时，遍历 `.module-experts/` 下所有专家/专题，逐个出报告
- **PROJECT.md（默认不审）**：`.module-experts/PROJECT.md`（项目级共享资产）**默认不纳入审查范围**；仅用户**显式声明**（如"连 PROJECT.md 一起核对"）时才纳入审查
- **资产位置**：默认项目级 `.module-experts/`；用户明确要求时才审查用户级 `~/.module-experts/`

## 执行流程

### Step 0：定位资产与确认范围

1. 读 `.module-experts/INDEX.md`，定位目标专家/专题的记录与目录
2. 确认模块根路径（从 INDEX / agent.md 读取）——后续 grep 验证以此为源码范围
3. 目标不存在 → 终止并提示可用专家清单

### Step 1：结构清点

对照 expert-team 的组织模型逐项核对（规范原文见 `use_skill("expert-team")`）：

| 检查项 | 要求 | 级别 |
|---|---|---|
| 必出文件 | `agent.md` + `C0-使用总览.md` + `C1-能力契约.md` + `implementation/01-架构.md` + `02-实现.md` 存在且非空 | P0 |
| 条件必出 | 有数据落地 → `C4-数据流向与消费.md` 存在；**模块有测试时** → `implementation/06-测试.md` + `test/known-failures.md` 存在（**PROJECT.md 标注「❌ 无法运行 / 无测试」的服务除外**——按「测试不可运行跳过」规则不强制必出） | P1 |
| 层级规则 | 子专家仅一级（`sub-experts/` 下无嵌套）；专题不嵌套、不含 `implementation/`、含 `topic.md` + `T0-专题总览.md` | P1 |
| INDEX 记录 | 该专家/专题在 INDEX.md 有记录，且含**匹配关键词**行（8~15 个）与 **git commit 基线**行（语义见 expert-team「文档说明·资产基线 commit」；旧资产缺失不判违规，建议合并补全时刷新补上） | P1 |
| 命名规范 | 契约层 C 前缀、专题层 T 前缀、实现层数字前缀、目录中文业务名 | P2 |
| 无 CHANGELOG | 资产目录内不应存在 CHANGELOG（已废止机制） | P2 |
| 项目共享资产 | `PROJECT.md`（存在时）：含项目信息/技术栈/架构形态/核心功能/核心服务清单（含代码位置/**测试可执行性**）/配套服务关系/架构图/数据流向图/运行环境 | P2（**仅显式声明时检查**） |

### Step 2：轨道A——使用者冷读测试（核心）

> **冷读纪律**：本步骤分两遍。**第一遍只读文档、禁止看源码**，以零上下文用户身份记录所有"看不懂 / 存疑 / 没法照做"的点；**第二遍对照源码验证**，区分是文档问题还是初读误解。跳过第一遍直接对照源码 = 生成者视角复检，审查失效。

五项测试：

| # | 测试 | 方法 | 不过的典型信号 |
|---|------|------|----------------|
| 1 | **冷读三问**（C0） | 只读 C0，尝试回答：这模块是干嘛的？怎么调用核心能力？会踩什么坑？ | 能力清单是文件名罗列而非能力描述；边界/坑一句没有或全是套话 |
| 2 | **术语自足** | 通读契约层，标出所有内部术语/黑话，检查首次出现处是否有解释 | "走 XX 通道时需先挂 YY 钩子"——XX/YY 全文无解释 |
| 3 | **示例照做**（C1/C2/C3） | 模拟"照抄示例写调用代码"：签名、参数、导入是否齐全可抄；第二遍抽样 ≥3 个示例 grep 源码验证 API 签名真实存在，并顺带核对该 API 的契约描述（参数行为语义/约束）与源码分支或测试是否矛盾 | 伪代码、`...` 省略关键参数、签名与源码不符、契约描述的行为与代码矛盾、写的是被调用方实现而非使用方代码 |
| 4 | **导航可达**（implementation/） | 每篇抽样 ≥3 个章节来源的关键符号，grep 源码验证命中 | 符号不存在（笔误/已重命名）、只标了路径但文件数千行无从下手 |
| 5 | **视角污染** | 契约层是否混入实现细节（算法/私有方法/内部结构/DB schema/实现模式名，即 CR3）；实现层是否复述契约而非引用 | C1 里讲"内部用跳表实现所以快" |

**判定**：测试 1/3 不过 → P0（用户会用错或根本用不起来）；测试 2/4 不过 → P1（能用但费劲）；测试 5 → 按 CR3 级别定 P1。

### Step 3：轨道B——格式合规

按 expert-team 内嵌规则逐篇自检，**只判定不重复规则原文**：

- **实现层**：R1–R7（cite 块 / 中文锚点目录 / 章节来源含 file:// 路径 + 关键符号 / 图表来源 / file:// 前缀 / 符号真实可 grep / ≥2 设计维度 + Mermaid）
- **契约层**：CR1–CR9（C0 四要素 / C1 六要素含行为语义与真实示例 / 无实现细节 / 契约来源为类名方法签名 / 已知坑三要素 / C4 黑盒消费视角）
- **INDEX**：记录格式与 expert-team Step 7 的模板一致，关键词行齐全；**基线一致性**：INDEX 的 git commit 与 agent.md/topic.md 出处行的基线一致（不一致 → P1，修复路径：expert-team 合并补全时刷新；禁止本 skill 代改——基线须真实对应资产创建/更新时刻，代填 HEAD 会掩盖未核对变更）
- **测试信息**：`06-测试.md` 含测试可执行性（运行命令/环境依赖/已知失败）；`test/known-failures.md` 切面级标注（子专家/功能域各自标注）且每条含**执行方式**（运行该测试的完整命令）
- error 级违规 → P1；warning 级违规 → P2（与轨道A 重叠的项不重复计，如 R6 符号真实性已由测试 4 覆盖）

### Step 4：问题分级与自动修复

**分级**：

| 级别 | 判据 | 处理 |
|------|------|------|
| P0 | 用户会用错或完全看不懂：冷读三问答不出、示例签名与源码不符、必出文档缺失/空壳、契约与代码行为矛盾 | 必须处理；在报告置顶 |
| P1 | 能用但低效：术语不自足、符号 grep 不中、结构/INDEX 违规、error 级格式违规 | 建议处理 |
| P2 | 瑕疵：warning 级格式违规、命名不规范、措辞 | 可选处理 |

**自动修复白名单**（仅限不需要重新调研源码即可完成的机械修正，静默执行、报告中一并列出）：

- 目录锚点与章节不对应 → 修正锚点
- 引用路径缺 `file://` 前缀 → 补前缀
- Mermaid 图缺 `图表来源` → 从所在章节的章节来源补
- INDEX 记录缺字段行（如匹配关键词行）→ 从 agent.md / C0 提取补建
- 无内容章节未标「该模块无此项」→ 补标注
- 文件命名不规范 → 重命名并同步 INDEX / 交叉引用

**禁止自动修复**（报告 + 修复路径，不代改）：

- 一切**内容级**问题：冷读不过、术语缺解释、示例失真、符号错误的正确值、契约缺失/编造——修复需要重新调研源码，路径：契约层小修 → expert-lookup 受限增量更新；结构性缺失/实现层问题 → expert-team 合并补全或重建
- 理由：审查者当场编内容 = 用一个未经调研的答案掩盖问题，比留着问题更危险

### Step 5：输出审查报告

默认在对话中输出；用户要求落盘时写 `review/expert-audit-{专家名}-{date}.md`。

```markdown
# 专家资产审查报告：{专家名}

**核心判据结论**：✅ 零上下文用户可看懂并照用 / ⚠️ 部分可用（见 P0/P1） / ❌ 不可用
**统计**：P0 ×N / P1 ×N / P2 ×N　自动修复 ×N

## 冷读三问回答（轨道A 测试 1 的实际回答，作为证据）
- 这模块是干嘛的：{凭 C0 给出的回答，答不出则写"答不出——{缺什么}"}
- 怎么调用核心能力：{...}
- 会踩什么坑：{...}

## P0（必须处理）
| # | 位置 | 问题 | 证据 | 修复路径 |
|---|------|------|------|----------|

## P1（建议处理）/ P2（可选）
（同表结构）

## 已自动修复
- {文件}：{修复内容}
```

## 行为边界

- **只审查不重建**：内容级修复一律指路 expert-team / expert-lookup，本 skill 不代写内容
- **冷读纪律不可跳**：第一遍禁止看源码；全量模式下每个专家同样两遍
- **抽样即可**：示例与符号验证抽样 ≥3（不足则全查），不逐条穷举；报告注明抽样范围
- **全量/大专题可并行**：待审专家 ≥2 时可用 task-dispatch 派子 agent 并行审查，每子 agent 负责一个专家——子 agent 天然零上下文，更贴合冷读纪律；主 agent 合并各报告
- **不审查源代码质量**：源码问题（bug/坏味道）不在范围，只审"文档是否如实、可懂地描述了它"
- **旧格式资产**：遇到旧行号标注（`#Lx-Ly`）不判违规、不迁移，仅在测试 4 中按"过期快照"对待并建议重建时切换
- **自动修复达 3 处以上**时在报告中汇总提示，异常多（>10）说明资产可能是旧格式，建议走 expert-team 合并补全而非零碎修
- **PROJECT.md 默认不审**：`.module-experts/PROJECT.md`（项目级共享资产）默认不纳入审查范围；仅用户显式声明时才审查其内容完整性（服务清单与专家资产对应、配套关系、图是否齐全等），其维护/更新由 expert-team 与 expert-lookup 负责

## 验证（测试方式）

1. 对一个刚生成的合格专家审查 → 冷读三问可答，P0 为 0
2. 人为删掉 C0 的"已知坑"章节 → 测试 1 报 P0
3. 人为把 C1 某示例参数改错 → 测试 3 抽样 grep 报 P0
4. 人为改坏一个章节来源符号 → 测试 4 报 P1
5. 删掉 INDEX 关键词行 → Step 1 报 P1 且自动补建
6. 对专题审查 → 覆盖专题层 + 其下全部专家，层级违规可检出
7. 显式声明审查 PROJECT.md 时 → 内容完整性可检出（服务清单/配套关系/架构图/数据流向图/运行环境）；默认不审时不被触发
8. INDEX 缺 git commit 基线行 / INDEX 与 agent.md·topic.md 基线不一致 → 可检出（P1）且修复路径指向 expert-team 刷新，本 skill 不代改