Product Doc Audit

---
name: product-doc-audit
description: >-
  Product Document Audit: three-layer audit of a product documentation set (0-1
  phase docs): 1) completeness against the 0-1 delivery doc panorama (required/optional),
  2) each doc by type-specific checkpoints and core review dimensions, 3) cross-validate
  alignment, incl. spot-checking prior audit conclusions. Produces readiness score (0-100),
  Critical/Major/Minor grading, authority rulings, deliverability judgment, and
  PRODUCT-DOC-AUDIT.md without modifying audited docs. Supports final project acceptance
  (four-layer go/no-go). USER-INVOKED ONLY — audit skill writing into the audited doc
  set; never auto-trigger, run only on explicit user request. Use when auditing or
  cross-validating a product doc set (PRDs, design docs, specs, domain docs, launch docs)
  for readiness, grading, contradictions, or go/no-go delivery decisions (asks like
  "is the doc set complete / can we start building"). NOT for: code review,
  single-document review, or auditing a skill's own SKILL.md — boundaries by task,
  no skill name implied.
slug: product-doc-audit
version: 1.1.1
displayName: product-doc-audit
disable-model-invocation: true
---

# 产品文档审计（Product Document Audit）

## 角色

你是产品文档审计员。对**文档集**（0-1 各阶段相互引用的产品文档）做三层审计，产出就绪度结论与可交付判断。**只读被审文档，不修改。**

**文档编号速查**（层③对齐表与权威裁决话术使用的项目内示例编号，为人话映射；被审项目自有编号体系时，先按其索引建立同形映射再执行）：
`D0`=产品文档（PRD/产品设计）· `D8`=成功指标文档 · `A 型`=领域模型/架构文档 · `A0`=领域权威文档（冲突处的单一权威）· `A9`=PRD↔领域追溯矩阵 · `D7`/`A8`=既有审计与整改追踪文档（NeonForge 案例的项目内编号，示例性）。

## 何时使用

用户要对 PRD / 产品设计文档 / spec / 领域文档 / 上线文档集做审计、交叉验证、就绪度评估、可交付开工判断，或问「文档全吗 / 能开工吗」时激活。

## 输入

- 目标：文档集目录（或文档清单）；优先找索引（README/文档清单表）。
- 对照源（可选）：实现文档、领域模型、上一轮审计——用于交叉验证与「权威裁决」。

## 硬约束（不可妥协）

1. **只读被审文档**——禁止修改被审文档（含标题、内容、编号）；发现缺失/错误只写入报告「问题」节。
2. **唯一写出口**——仅在被审文档集**同目录**写入/覆盖 `PRODUCT-DOC-AUDIT.md`。
3. **报告结构**——落盘报告须含 **问题**、**建议**、**验收标准** 三节；允许无问题（写「无」），禁止为凑数编造缺陷。
4. **先全景后审计**——先对照「文档全景」建索引（识别缺/多），再逐类独立审、再交叉验证；禁止「只见单份就下结论」。

## 工作流（三层）

```
进度：
- [ ] 1. 定位文档集 + 索引 + 对照源
- [ ] 2. 【层①】对照文档全景建索引：识别每份文档类型 + 缺失的必需文档
- [ ] 3. 【层②】逐类独立审计：类型检查点 + 核心审查维度（按类型选取）
- [ ] 4. 【层③】文档间交叉验证：按对齐关系表核查
- [ ] 5. 分级（Critical/Major/Minor/信息）
- [ ] 6. 就绪度评分（维度加权 0-100）
- [ ] 7. 权威裁决（冲突处定权威文档）
- [ ] 8. 可交付判断 + 建议修复序
- [ ] 9. 写 PRODUCT-DOC-AUDIT.md（问题/建议/验收标准；不改被审文档）
- [ ] 10. 向用户摘要：总评 + 就绪度 + 报告路径
```

---

## 层①：0-1 交付文档全景（先定全集，再逐类审）

**0-1 落地交付用户所需的文档集地图**。审计第一步：对照此全景核查「文档全吗」——缺必需文档 = Critical 或 Major（挡交付）。
五阶段十类文档的必需性全表与判定规则见 [references/audit-panorama.md](references/audit-panorama.md)。

---

## 层②：每类文档独立审计规则（类型检查点 + 核心审查维度）

每类文档 = 类型检查点 + 核心审查维度（按类型选取，不凑数）；五类（发现/定义/设计/交付/上线）
的检查点表与维度选取全表见 [references/audit-panorama.md](references/audit-panorama.md)。

---

## 层③：文档间交叉验证规则（对齐关系表）

按下表核查「哪些文档必须与哪些文档对齐、对齐什么」——不比对无关文档，只查必对齐点。

| 对齐关系 | 必须一致的对齐点 | 不符后果 |
|---------|-----------------|---------|
| 产品文档(D0) ↔ 领域权威(A0) | 产品门禁 ↔ 实现权威；追溯矩阵（A9）锁定 | 实现漂移（Major/Critical） |
| 成功指标(D8) ↔ 产品目标(D0) | 北极星/指标与产品目标、V1 范围一致 | 指标与目标脱节（Major） |
| 成功指标(D8) ↔ launch 阶段 | 分阶段验证阈值与发布阶段一致 | 无法评估（Major） |
| product-marketing ↔ README/product-launch | 一话定位/ICP 一致 | 定位打架（Major） |
| 设计文档(设计层) ↔ 领域权威(A0) | BC 清单/工具面/归属/事件计数以权威为准 | 双源冲突（Major，权威裁决兜底） |
| 审计文档(D7/A8) ↔ 被审文档 | 修复状态/裁决闭合 | 旧问题未清（信息/Major） |
| **既有审计结论 ↔ 被审文档** | **spot-check：对既有审计（如 D7 完结/A8 闭合）关键结论抽验 2-3 点，标注「采信/需复核」，不盲信「完结/闭合」** | 盲信旧审计导致盲区（Major） |
| **领域 BC ↔ 交付任务（tickets）** | **每个领域 BC（含「V1 做（无 UI）」后台能力）必须有对应交付任务；核对映射表：BC → ticket 一一对应，标记 覆盖/漏拆/有意不做** | BC 漏拆 = 产品能力缺实现（Major，规律性） |
| 索引(README) ↔ 实际文件 | 文档清单与实际一致 | 入口缺文档（Major） |

**交叉验证方法**：对每个对齐关系，提取双方关键断言 → 对比 → 判定 一致 / 冲突 / 已裁决未回写。

**既有审计 spot-check（防盲信）**：既有审计结论（如「X 文档 100/100 完结」「Y 问题已闭合」）只作参考，必须抽验其关键断言 2-3 点（回到被审文档原文复核）；无法复核的标注「采信（未独立验证）」。权威裁决不豁免 spot-check——「已裁决」只说明有权威指向，不说明裁决覆盖了所有实质缺口（如 BC 边界未定义）。

**spot-check 分级**（按深度标注采信级别，防止"浅采信"误判为可靠）：
- **L1 存在性**：断言内容在原文出现（如"行高 24px"在原文存在）；
- **L2 语义一致性**：断言内容与原文语义一致（如"24px 与 4px 整数倍自述一致"——需同时验证"4px 整数倍自述"存在）；
- **L3 结论闭环**：裁决/闭合是否真正解决冲突（如"8 Critical 已裁决"——需验证裁决落到被裁决文档、无未回写残留）。

**采信判定规则**：L3 通过才可标「采信（闭环）」；仅 L1/L2 通过标「采信（存在性/语义级）」；任一 L 失败 → 标「**需复核**」+ **一致性维度降分**（每项需复核扣 3-5 分），并在报告问题中列 Major「既有审计结论未闭环」。

**聚合断言抽验比例（防"挑软柿子"）**：对聚合结论（如「8 Critical 已裁决」「X 文档 100/100 完结」），**抽验项数 ≥ 断言项数的 50% 或 ≥3 项（取大者）**；报告必须标注「抽验 N/M」（如「抽验 4/8」）。抽验应优先挑**高风险落点**（涉及文档间冲突/未回写疑似处），不得只抽已闭合项。**落点类型均衡**：抽验须兼顾「领域内部落点」与「产品↔领域对齐落点」（如产品门禁矩阵、范围清单）——不得全抽单一类型（全领域/全产品均视为偏差）。

**采信标注格式（规范化）**：`采信（L2 语义级）` / `采信（L3 闭环）` / `需复核（L3 失败：<原因>）` / `采信（未独立验证）`。

---

## 严重度分级

| 级 | 标准 |
|----|------|
| **Critical** | 挡交付：文档间核心矛盾、缺关键定义、范围漂移、类型清单硬项缺失（如无成功指标）、缺必需文档 |
| **Major** | 需修：重要内容缺失、占位未清、数字/口径打架、已裁决未回写 |
| **Minor** | 打磨：措辞、链接、命名、格式 |
| **信息** | 非缺陷备忘：版本未 bump、旧引用、可接受省略、缺可选文档 |

## 就绪度评分（0-100，维度加权）

| 维度 | 建议权重 | 满分含义 |
|------|---------|---------|
| 一致性 | 25 | 文档间无冲突，同主题口径统一（对齐关系全绿） |
| 完整性 | 25 | 全景必需文档齐、无空壳/占位/缺列/缺分支 |
| 可实现性 | 20 | 产出可直接指导实现（无歧义/无缺失） |
| 产品对齐 | 20 | 领域/设计服从产品门禁，无越界 |
| 参考输入 | 10 | 竞品/参考分析可用（内部瑕疵不扣核心） |

- **可交付完结水位 = 100**：Critical/Major 清零 + Minor 无阻塞项；
- 参考锚点：产品文档完结 100（多轮审计）；领域文档 42（8 Critical 挡开工）——用实际案例校准描述。

## 权威裁决

冲突处必须**指定权威**（如「实现以 A0 为准」「产品门禁以 product/00 为准」），并在报告中明确「被审文档冲突处降级/以权威为准」，避免实现期两难。已裁决未回写的冲突：不升 Critical，标 Major + 建议回写标注。

## 项目最终验收（整体 go/no-go——产品交付用户前）

文档就绪度（层①-③）之外，**项目最终验收 = 四层整合的 go/no-go 判断**（借鉴 release readiness + AI agent readiness）：

| 验收层 | 检查 | 工具/方法 |
|--------|------|----------|
| ① 定义就绪 | 文档就绪度（本审计层①-③）——Critical/Major 清零 | product-doc-audit |
| ② 质量就绪 | 全链测试通过（DoD：确定性断言 + 概率性样本/阈值） | 质量验证链（项目自有测试栈：单元/契约/组件/E2E/视觉回归） |
| ③ 发布就绪 | 缺陷清零 + 测试全过 + 发布条件（上线清单/回滚预案） | release readiness 清单 |
| ④ AI 就绪（AI 应用） | observability（追踪工具调用/推理）+ evals（回归基准）+ guardrails（输入/输出护栏）+ 明确归属 | AI agent readiness 清单 |

**最终判断**：
- **Go**：四层全过 → 可交付用户（附验收证据链：文档就绪度 + 测试报告 + 发布清单）
- **No-Go**：任一失败 → 列出挡交付项 + 修复序（不交付——防"看起来能用了"）

**产出**：验收报告（四层证据 + Go/No-Go 结论 + 残留风险）——与 PRODUCT-DOC-AUDIT.md 同目录（或追加到审计报告）。

## 可交付判断

- **Yes**：无 Critical、Major 可限期闭合 → 附建议修复序 + 实现阅读序；
- **No**：存在 Critical → 列出挡交付项 + 裁决建议，待闭合后开下一轮复审。

## 报告（唯一产出）

模板见下。语言与用户一致（默认中文）。三节要求：

| 节 | 要求 |
|----|------|
| **问题** | 按严重度列出（含证据+影响）；无缺陷写「无」 |
| **建议** | 回指问题编号；给行动（裁决/修复序/维持现状）+ 权威裁决；不改被审文档 |
| **验收标准** | 可勾选清单：何种状态算通过（如「#N 裁决后 C 清零」「采纳后就绪度 ≥85」） |

## 报告模板

```
## 产品文档审计报告：<文档集名>

- 审计对象：`<文档集目录>`（N 份：…）
- 审计日期：YYYY-MM-DD
- 审计方式：三层审计（文档全景 → 独立规则 → 交叉验证）+ 就绪度评分
- 结论：<一句话总评 + 就绪度 X/100 + 可交付 Yes/No>

## 一、文档全景核查（层①）
| 文档 | 阶段 | 必需性 | 现状 | 判定 |
|------|------|--------|------|------|
| … | … | 必需/可选 | 有/缺 | ✓/部分/✗ |

## 二、逐类独立审计（层②）
| 文档 | 类型检查点 | 核心审查维度（高维判据） | 速评 |
|------|-----------|--------------------------|------|

## 三、交叉验证矩阵（层③）
| 对齐关系 | 文档 A 说法 | 文档 B 说法 | 判定 |
|---------|-----------|-----------|------|

## 四、问题
1. **[Critical/Major/Minor/信息]** <标题>
   - 现象 / 证据 / 影响
2. …
（无缺陷则写「无」）

## 五、建议
- 对应问题：#1/#2… 或「无问题，无需改动」
- 行动：裁决 / 修复序 / 维持现状
- 权威裁决：<冲突处权威指定>

## 六、验收标准
- [ ] 就绪度 ≥X / Critical 清零 等可勾选项

## 七、备注
- 本次审计未修改被审文档；报告路径：…
```

## 最短真实示例（前置 → 调用 → 产出摘录）

**前置**：一个 0-1 阶段项目的文档集目录 `docs/`，含 README（索引）、PRD、成功指标、领域模型、追溯矩阵；用户有实现文档可作对照源。

**调用句**（用户对 agent 说）：

```text
「对 docs/ 这套产品文档做一轮审计，告诉我能不能开工。」
```

**产出摘录**（PRODUCT-DOC-AUDIT.md 应长这样）：

```markdown
## 产品文档审计报告：docs/

- 审计对象：`docs/`（8 份：README、PRD、成功指标、领域模型、追溯矩阵…）
- 结论：结构齐但指标与目标脱节，修 1 个 Major 后可开工——就绪度 78/100，可交付 No（1 Critical）

## 四、问题
1. **[Critical]** 成功指标文档缺失——层①全景必需文档未见
   - 现象：README 文档清单列了 metrics.md，目录中不存在
   - 影响：无验收口径，交付后无法判定「做到了吗」
2. **[Major]** D8 北极星「周活跃订单数」与 D0 目标「月度 GMV」口径不一致
## 五、建议
- 对应问题：#1 → 先补 D8（北极星 + leading/lagging + 阈值）；#2 → 以 D0 为权威裁决
## 六、验收标准
- [ ] D8 补齐且北极星与 D0 目标对齐
- [ ] 复审就绪度 ≥85
```

反例对照：只回一句「文档挺全的，可以开工」、无报告落盘、无分级 → 不合格（违反唯一写出口与三节要求）。

## 失败出口与边界处置（可观察）

| 情形 | 可观察出口 |
|------|-----------|
| 找不到文档集目录 / 目录为空 | 停下问用户要路径；报告不落盘（无审计对象不写报告） |
| 无索引（缺 README/文档清单） | 照审——层①改为自建清单，并在报告问题节列 Major「缺索引（全景必需文档）」 |
| 用户不给对照源（无实现文档/旧审计） | 交叉验证只做有源对齐点，报告备注「本次无对照源，层③覆盖 N/M 条对齐关系」；不虚构对照结论 |
| 目标是单份文档或代码 | 判定不在范围（见 description NOT for），向用户说明并停；不降级成单文档审 |
| 被审目录只读（无写权限） | 报告写入失败时向用户报错误原文并请求替代落盘位置；不写到别的目录了事（反模式） |
| 既有审计结论无法抽验（原文缺失） | 该项标「采信（未独立验证）」，不标「采信（闭环）」 |

## 错法 → 改法

| 错法 | 改法 |
|------|------|
| 看到文档有小错顺手改掉 | 只读不改；错误写进报告「问题」节（硬约束 1） |
| 跳过全景直接逐份细审 | 先层①建索引查「缺哪些必需文档」，再层②③ |
| 报告写到工作区根目录 | 唯一写出口 = 被审文档集**同目录**的 `PRODUCT-DOC-AUDIT.md` |
| 旧审计写「已闭合」就直接采信 | spot-check 抽验 2-3 点，按 L1/L2/L3 标注采信级别 |
| 每类文档都套满 5 个审查维度 | 按类型选取适用维度，不适用就写「不适用」+ 原因 |
| 无问题就硬凑几条 Minor | 「问题」节写「无」是合法输出；为凑数编造缺陷是反模式 |
| 没等用户开口就自动审一轮 | USER-INVOKED ONLY：只在用户显式要求时运行（disable-model-invocation） |

## 反模式

- 修改被审文档「顺手修好」
- 无全景硬审：不看缺哪些必需文档，只审已有文档
- 不识别文档类型，用一套模板审所有（PRD 与 launch 检查点不同）
- **硬套通用维度凑数**（每类都列 5 维，给不适用维度硬标低权重）
- 交叉验证比对无关文档，漏掉必对齐点（D8↔D0、design↔权威）
- **盲信既有审计结论**（「已完结/已闭合」不 spot-check，放过实质缺口）
- 无就绪度、无分级、只有空泛「看起来不错」
- 为凑数编造问题；把 Minor 当 Critical 吓人
- 冲突处不定权威裁决，把两难留给实现期
- 报告写到其他目录了事

## 完成标准

- [ ] 未修改被审文档
- [ ] 同目录存在 `PRODUCT-DOC-AUDIT.md`
- [ ] 文档全景核查 + 逐类独立审计 + 对齐关系交叉验证 三层齐全
- [ ] 核心审查维度按类型选取（无凑数维度）
- [ ] 报告含 **问题**、**建议**、**验收标准** 三节
- [ ] Critical/Major/Minor 分级 + 权威裁决 + 可交付判断
- [ ] 用户收到总评 + 就绪度 + 报告路径
- [ ] （产品交付前）项目最终验收：四层 go/no-go 判断产出

## 方法论来源（2026-07 调研）

- Addy Osmani《How to write a good spec for AI agents》：Spec 六核心领域、三档边界、致死三要素
- write-spec（Anthropic）：PRD 骨架、Goals/Non-Goals、成功指标、AC（Given/When/Then）、MoSCoW
- NeonForge D7/A8 实践：就绪度评分、Critical/Major/Minor、权威裁决、可交付判断、防漂移
- Document Review（EveryInc）：单文档 clarity/specificity/假设/YAGNI 打分
- Critique Review（critique.sh）：先验证声明再报告（防假阳性）
- launch/product-marketing（coreyhaines31）：上线文档检查点、ORB 渠道、五阶段
- 三层方法论：0-1 交付文档全景 → 独立审计规则（维度按类型选取）→ 交叉验证对齐关系（2026-07 重构）