spec-reality-audit

name	spec-reality-audit
description	对比"规格文档描述的"与"实际数据/代码中存在的"，生成结构化审计清单。适用于文件完整性审计、API 端点审计、数据库 schema 审计、配置审计、测试覆盖审计等场景。

Spec-Reality Audit 规格与现实审计 Skill

概述

本 Skill 执行"规格 vs 现实"审计：读取一份规格文档（PRD、设计文档、API spec 等），并行枚举多个真实数据样本，交叉比对生成完整清单、覆盖矩阵、命名变体速查表，以及与规格文档的差异分析。

核心原则：多样本交叉验证 → 区分必备/可选 → 检测变体 → 反哺规格文档。

触发条件

当用户需求匹配以下模式时激活：

• 对比文档/规格说的 vs 实际数据/代码中有的
• 生成审计清单、覆盖矩阵
• 检查规格文档的完整性或准确性
• 关键词：审计、清单、覆盖矩阵、spec audit、reality check、completeness check

不适用场景

• 从规范 PDF 中提取条款 → 使用 reg-extractor
• 迭代修改 PRD 文档本身 → 使用 iterative-prd
• 单纯的文件搜索或目录列举（无需与规格对比）

Phase 0: 参数确认

与用户确认以下参数，缺省时主动建议合理默认值：

参数	说明	示例
spec_path	规格文档路径	docs/prd.md
sample_paths	真实数据样本路径列表（≥2 个）	项目测试数据/项目1/送审版, 项目测试数据/项目2/送审版, ...
audit_scope	审计范围描述	"文件完整性"、"API 端点覆盖"、"数据库表结构"
output_path	输出文件路径	docs/file_checklist.md
hierarchy	清单层级结构	"项目级 + 子工程级"、"模块级 + 接口级"

确认后进入 Phase 1。

Phase 1: 数据枚举（并行）

必须并行读取所有样本，不可串行逐个处理。

1. 使用 Task 工具并行启动多个 Explore subagent，每个 subagent 负责一个 sample_path：
   • 递归枚举全部条目（目录树 / 端点列表 / 表结构等）
   • 生成该样本的结构化清单
2. 同时读取 spec_path，提取规格中定义的分类体系（如 PRD 的文件类型编号 F0-F10）
3. 汇总所有样本的枚举结果，统一条目命名格式

输出：每个样本的结构化条目列表 + 规格文档的分类体系。

Phase 2: 交叉比对

跨样本比对，对每个条目判定覆盖类型：

覆盖类型	判定规则	标记
必备	所有样本都有	必备
可选	部分样本有（≥2 个但非全部）	可选
如有	仅单个样本有	如有

输出覆盖矩阵表：行 = 条目，列 = 各样本，单元格 = ✅/❌。

Hard Gate：覆盖矩阵必须覆盖所有样本 × 所有条目，不可遗漏。

Phase 3: 变体检测

基于 Phase 1 的实际数据（不可凭空推测），识别以下变体类型：

变体类型	说明	示例
同义词	同一概念的不同命名	可研报告 / 初设报告 / 设计报告
格式差异	分隔符、括号、编码	全角括号（） vs 半角括号()
阶段术语	不同阶段的术语升级	估算书 → 概算书
结构差异	同一内容的不同组织方式	独立目录 vs 合并在父目录内

输出：变体速查表（标准概念 → 各样本中的实际名称）。

Phase 4: 规格差异分析

必须逐一对照 spec 中的每个分类项，不可跳过。

将 Phase 2 的完整清单与 spec 中的分类体系逐一对照，标注三类差异：

差异类型	说明	示例
粒度不足	spec 只到大类，实际有子类	PRD 仅定义 F1"可研/初设报告"，实际有报告、图纸、概算书等子文件
准确性问题	spec 描述与实际不符	PRD 标记 F8 为可选件，实际仅在审定版出现（送审版无）
遗漏项	实际存在但 spec 未提及	拆除设备清单、PML 柜子工程等 PRD 未覆盖

同时标注 spec 中有但实际样本中均不存在的"幽灵项"。

输出：差异说明表 + 对 spec 的修订建议。

Phase 5: 组装输出

按用户在 Phase 0 确认的 hierarchy 组装最终文档，固定包含以下章节：

1. 元信息（版本、日期、数据来源、用途）
2. 完整清单（按层级展开）
   - 每条含：标准名称、必备/可选/如有、格式、命名变体、备注
3. 命名变体速查表
   - 按变体类型分节：同义词、格式差异、阶段术语、结构差异
4. 与规格文档的差异说明
   - 粒度不足、准确性修正、遗漏项、修订建议
5. 覆盖矩阵附录
   - 行 = 条目，列 = 各样本，单元格 = ✅/❌

Hard Gate：输出文档必须包含"与规格文档的差异说明"章节。

Hard Gates 汇总

1. Phase 1 必须并行读取所有样本，不可串行逐个处理
2. Phase 2 的覆盖矩阵必须覆盖所有样本 × 所有条目，不可遗漏
3. Phase 4 必须逐一对照 spec 中的每个分类项，不可跳过
4. 输出文档必须包含"与规格文档的差异说明"章节
5. 变体速查表必须基于实际数据，不可凭空推测

常见错误

错误	正确做法
串行处理样本，遗漏某个样本的条目	并行枚举，汇总后统一比对
只列举 spec 中提到的条目	以实际数据为主，spec 为辅；实际有而 spec 无的也要列出
变体表中编造不存在的变体	每个变体必须标注出现在哪个样本中
跳过 spec 中某些分类项的对照	逐一对照，即使该分类在实际中完全匹配也要确认
输出缺少差异说明章节	即使无差异也要写"经对照，spec 与实际完全一致"

示例：文件完整性审计

以 Setri 项目的文件清单创建过程为例：

输入参数：

• spec_path: docs/prd.md（PRD v0.2，含 F0-F10 文件分类）
• sample_paths: 3 个测试项目的送审版目录
• audit_scope: 文件完整性
• output_path: docs/file_checklist.md
• hierarchy: 项目级 + 子工程级

执行摘要：

• Phase 1: 并行枚举 3 个项目目录，提取 PRD 的 F0-F10 分类
• Phase 2: 交叉比对发现 7 类必备件 + 4 类可选件 + 17 类参考文件；子工程级 7 种类型
• Phase 3: 识别 5 类变体（同义词、括号、阶段术语、分隔符、结构差异）
• Phase 4: 发现 PRD 粒度不足（子工程级未展开）、准确性修正 3 处、遗漏项 5 类
• Phase 5: 输出 275 行结构化清单，含覆盖矩阵和差异说明

产出文件： docs/file_checklist.md

与其他技能的关系

技能	关系
reg-extractor	互补：reg-extractor 提取规范条款，spec-reality-audit 审计规格与现实的差距
iterative-prd	上下游：audit 产出的差异说明可作为 PRD 修订的输入