audit-readme git:20260730.6ee304aA

Immutable. This exact content is served forever at /api/v1/blob/01e8fbc3066a9609.

---
name: audit-readme
description: README / 用户使用文档专项审查维度 RM-1~RM-6 — 聚焦用户路径、快速开始、示例真实度、配置排错与消费链一致性
---
# Audit Readme Skill

## 适用范围

当审查目标是 `README.md` 或承担主使用入口职责的用户使用文档时，在 `audit-document` 的通用文档维度之上，叠加本 Skill。

若目标是站点文档、最终用户使用文档、最终用户手册、接入手册、公开能力页、项目文档设计或菜单导航审查，先使用 `audit-user-manual` 聚合 `user-manual-authoring`、`audit-document`、本 Skill、`review-checklist`、`document-sync` 与 `test-router` 的证据；落点为 README 或项目主文档时，再叠加本 Skill 的 RM-1~RM-6。

## 维度总览（RM-1~RM-6）

| 分组 | 维度 | 优先级 |
|------|------|:------:|
| A — 用户路径 | RM-1 用户路径完整性 · RM-2 快速开始可执行性 | 🔴 |
| B — 内容可信度 | RM-3 示例真实度 · RM-4 配置与排错可发现性 | 🔴/🟡 |
| C — 叙事与联动 | RM-5 开发信息后置性 · RM-6 消费链一致性 | 🟡/🔴 |

## 核心检查维度

**RM-1 用户路径完整性 🔴**
- 用户是否能快速知道“这是什么、适合谁、什么时候用”
- 文档是否给出从理解到第一次成功使用的完整路径
- 是否存在“只有能力说明，没有怎么开始”的断层
- 是否执行 `UserPerspectiveDocsGate`：从使用者真实任务出发组织，而不是按维护者内部实现、历史治理或仓库目录顺序堆叠
- 是否执行 `UserDocsPrimarySurfaceGate`：README、文档站或 quick start 的首页首屏、nav/sidebar 前两组、CTA、reference 入口是否先服务用户使用路径，而不是开发契约、目标 API、数据模型或实现验收
- 是否执行 `FinalUserManualFirstGate`：需求概况之后应先形成用户最终使用文档（文档站或至少 README），而不是先让开发文档、技术方案或实施计划占据主入口
- 是否执行 `DocsSiteInformationArchitectureGate` / `UserManualFlowAndFailureGate`：站点、README 或手册是否按真实用户任务、成功路径、失败恢复、限制和下一步组织，而不是把所有章节平铺给用户自己猜
- 是否执行 `UserManualProductizationGate`：README / quick start / 用户手册是否按最终使用者产品化组织受众、任务、配置、真实示例、排错、失败恢复和源码 / 示例可点击链路，内部字段和实现说明是否后置
- 多页文档站或 README 入口是否执行 `DocsPageRoleMatrixGate` / `CompleteUserManualSiteMatrixGate`，标明每页 role、audience、sourceOfTruth、nav/sidebar 位置和用户主路径状态

**RM-2 快速开始可执行性 🔴**
- 安装、启动、接入或运行步骤是否真实、完整、可执行
- 示例命令是否缺关键前置条件、环境变量、端口或依赖
- 最短成功路径是否足够短，避免把维护流程误当快速开始
- 用户第一次照着做时，是否能少跳转、少猜测、少补前置知识
- 快速开始含 Mermaid / 流程图 / 队列 / 异步 / 批处理示例时，是否执行 `UserManualRenderedFlowAndRealWorkflowProbe`，验证真实渲染并使用真实业务工作流
- 快速开始、fixture、mock 或 demo 是否执行 `ExpertOutputQualityGate`，先说明生产推荐路径、框架原生能力和真实接入方式，再标明样例的验证边界

**RM-3 示例真实度 🟡**
- 示例是否代表真实常见用法，而不是理想化伪代码
- 示例命名、参数、返回值是否与当前实现一致
- 示例是否帮助用户完成“第一次成功”
- 是否执行 `DocsExampleTruthSurfaceGate`：README / quick start 中的 option、config、method、field、导入路径或 CLI 参数必须能在 public types、runtime wiring、配置 schema、导出入口或最小执行探针里找到证据
- 是否执行 `CallbackExampleScopeProbe`：callback / hook / event / transaction / handler / ctx 示例的参数签名、ctx 字段、闭包变量、返回值和异常语义是否匹配当前实现
- 是否执行 `ExpertOutputQualityGate`：示例是否体现资深技术视角，明确区分推荐实践、框架已有能力、测试 fixture/mock/demo 边界和反模式；不得把硬编码单例、每个 route 重复声明或仅证明底层能力存在的夹具当成用户主路径
- 性能表、语法/能力矩阵是否先给用户选择结论，再解释字段含义、支持形式、不支持形式和优先级示例
- 参数、配置、模式、状态、错误码和限制是否逐项解释到“普通使用者能看懂并知道怎么选”
- 队列、任务、异步或批处理类 README 是否执行 `QueueDocsRealWorkflowGate`：给出真实入队、执行、状态查询、失败重试、清理和常见失败恢复，而不是只展示单条硬编码样例

**RM-4 配置与排错可发现性 🟡**
- 用户最常遇到的配置点是否能被找到
- FAQ、报错、依赖缺失、权限、端口、登录态等排错信息是否易发现
- 是否存在“问题在文档里，但埋得太深”
- 是否执行 `UserDocsImmediateComprehensionGate`：配置字段、默认值、选择建议、错误与排错是否简单易懂，并能让首次读者立即判断当前能做什么、不能做什么、怎么第一次成功

**RM-5 开发信息后置性 🟡**
- 开发方式、贡献流程、协作规范是否没有抢占主叙事
- README 是否优先服务使用者，而不是维护者
- 是否执行 `PublicUserDocsMaintainerBoundaryGate`：发布 checklist、维护者验收、内部同步清单、台账状态或复审任务不得作为公开 README / 用户文档的主路径
- 是否执行 `SideEffectCompatibilityDocsGate`：README / 快速上手不得把带全局副作用、兼容 shim、弃用行为或高心智负担的旧路径放入用户主路径
- 是否执行 `ExecutableExampleTruthProbeGate`：README 中 DSL、配置、模板或扩展示例需有当前实现的最小执行证据；未来语法必须标注 preview / unreleased
- 若同时面向用户与贡献者，是否保持单一主叙事中心

**RM-6 消费链一致性 🔴**
- README 与 `package.json`、CLI、website、examples、Profile、changelog 是否一致
- 版本号、命令、路径、配置项、能力声明是否同步
- 是否出现“README 说能做，其他入口说法不同”的漂移
- README 中“已支持 / 已接入 / 已验证 / 可运行”类声明是否有 `CodeTruthRequirementGate` 与 `LiveVerificationExecutionObligation` 证据
- README、comparison、scenario、index 或 generated search 发生行为语义变化时，是否执行 `BehaviorSemanticDocsParityGate`，用同义/历史术语矩阵反查 public API、runtime wiring、文档索引和生成搜索
- 多语言 README 或双语入口的支持/不支持、启用/禁用、同步/异步、缓存/刷新等负向语义是否执行 `NegativeTranslationParityProbe`
- README 若存在翻译页或 website 双入口，是否执行 `DocumentationTranslationParityGuard` 并保持信息等价
- README 是否遵守 `FormalDocsDevCodexBoundary`，没有混入运行时报告、台账、内部待办或一次性复盘口吻
- README 是否执行 `DocsConsumerSweep`：新增命令、字段、配置、导航顺序或能力声明后，website、Profile、examples、templates、validate probes 和代码消费点是否同步
- README 或文档站首页、quick start、公共用户路径变化时，是否执行 `UserPathContractSweep`，确认 README / website / nav/sidebar / examples / templates / validate probes / 部署副本与代码消费点同步
- 文档站主题、导航、搜索、代码高亮、移动端、暗色/亮色变化时，是否执行 `DocsThemeRuntimeVisualProbeGate`，基于真实运行态验证视觉和交互

## 与 audit-document 的边界

| 维度层 | 负责内容 |
|--------|----------|
| `audit-document` | 通用结构、准确性、链接、术语、受众适配、关联一致性 |
| `audit-readme` | 用户路径、快速开始、示例真实度、开发信息后置、消费链一致性 |

规则：

- 通用文档问题优先记在 `DA-*`
- README 专项问题记在 `RM-*`
- 不重复用两套维度描述同一个 finding

## 输出建议

审查 README 时，建议至少回答以下问题：

1. 用户能不能在 1 次阅读里完成第一次成功？
2. 如果失败，文档有没有给出足够靠前的排错线索？
3. 开发/贡献内容是否已经后置？
4. README 与其他当前消费者是否一致？
5. 性能、语法或能力矩阵是否避免内部术语优先，且说明了支持 / 不支持 / 优先级？
6. 文档是否足够详细、心智负担足够低，首次读者能否看懂每个关键字段、命令、状态和失败恢复路径？
7. 用户文档主面是否被开发契约替代？首页、quick start、nav/sidebar 和 CTA 是否仍优先回答“怎么使用”？
8. 若存在文档站或生成站点，是否验证了实际生成产物、TOC/sidebar/nav 去重、真实用户路径和部署副本同步？
9. README 是否区分生产推荐路径、fixture/mock/demo 边界和反模式，并给出框架原生能力或项目既有能力的专家级推荐？

## N/A 规则

- 纯内部占位 README、明确只做跳转门户页：RM-2 / RM-3 可按实际场景标注 N/A，但必须明确真实用户文档入口。
- 非 README 的架构文档、治理说明、贡献指南：本 Skill 不触发。
- 站点文档、最终用户手册、接入手册、项目文档设计或菜单导航但非 README：优先审查 `audit-user-manual` + `audit-document`，本 Skill 只在其承担 README / 主入口职责时叠加。