Skip to content

xinetzone/SpecWeave / .agents/skills/artifact-consistency-audit

artifact-consistency-audit

Verified

当用户要求核验、复检或体检某份产物与其源文档、上游清单或规范之间的一致性时使用——触发词:'检查…的修复细节'、'复验'、'体检'、'核验一致性'、'覆盖率核对'、'引用是否忠实'、'有无遗漏'、'修补后复验'、'对照源文档检查'。必须提供五步核验法(基准重读→覆盖率机械比对→引用逐字回验→交叉引用可达→分级发现清单),产出 P0-P3 分级发现与结论,默认只报告不修改。不要用目视翻查代替机械比对——本Skill封装双向集合比对、逐字回验、修补自身回验三条纪律,专防漏检与'修补引入新事实风险'。

产物一致性核验 Skill

⚠️ 本Skill是门面层(L1)。L0 见 ONBOARDING.md;链接存在性检查委托 check-links.py,不重复实现。

1. Skill ID

artifact-consistency-audit(对外名称:产物一致性核验 / Artifact Consistency Audit)

2. 功能描述

核验「派生产物 ↔ 源文档/上游清单/规范」的一致性,回答四个问题:有没有漏?引用忠不忠实?指向对不对?体例一致吗?

步名称产出
S1基准重读从磁盘重读双方原文(禁用记忆与会话摘要)
S2覆盖率机械比对双向集合比对结论(源 N 条 ↔ 产物 M 条,含幽灵项/缺失项)
S3引用逐字回验每条引文与源文对照结论(含引号、限定词、层级)
S4交叉引用可达章节号/文件名/锚点指向核验结论
S5分级发现清单P0–P3 发现 + 结论 + 可选修复建议

为什么必须机械比对而不能目视? 目视核验的漏检率随产物规模非线性上升,且漏检不可自知——你以为看完了。正则提取 ID 集合并做双向集合比对,把「有没有漏」从判断问题降级为计算问题,结论可复算、可复核。

为什么基准必须从磁盘重读? 会话摘要与上下文压缩会截断或过期,被核验文本若取自摘要,核验的是记忆而非事实。基准只能是磁盘原文。

3. 何时使用本技能

层级触发词行为
T2(强·直接执行)"核验一致性"、"复验修复细节"、"体检"、"检查有无遗漏"、"对照源文档检查"直接进入五步核验法
T1(中·确认后执行)"覆盖率核对"、"引用是否忠实"、"修补后复验"、"体例一致吗"确认核验范围后执行
T0(弱·仅提示)"一致性"、"核验"、"检查一下"先确认被核验对象与基准,再决定是否进入本流程

适用:派生产物(报告/清单/摘要/视图)与其源文档的一致性;修补提交后的复验;跨文件体例一致性。 不适用:链接存在性单点检查(用 link-check-cmd)、代码重复检查(用 check-duplication-cmd)、提交前流水线(用 ci-check-cmd)、从零评审一份无基准的文档。

4. 方案选择决策

被核验对象是什么?
├─ 单份产物 ↔ 单份源文档(覆盖率 + 忠实度)? → 方案 A:标准五步(S1→S5)
├─ 刚做完修补,需复验修补本身? → 方案 B:修补后复验(S1→S5 + S3 强化"修补自身回验")
├─ 一组产物 ↔ 多个源/规范(跨文件体例)? → 方案 C:全量集审计(先建基准台账,再逐对核验)
└─ 仅想确认某引用是否可达/存在? → 不适用本Skill,转 link-check-cmd

5. 核心步骤

S1 基准重读(零记忆)

  • 用 Read/Grep 从磁盘重读双方原文:被核验产物 + 其声明的源(源文档、上游清单、规范条款)
  • 记录双方路径与行号;若产物声明了"唯一事实来源",把它作为比对基准

S2 覆盖率机械比对(双向)

  • 对源与产物分别用正则提取结构化标识(编号 ID、条目标题、表行),得到两个集合
  • 双向比对:源有产物无 = 缺失;产物有源无 = 幽灵项;两侧计数须与文档自称的数字自洽
  • 禁止抽样;全量提取

S3 引用逐字回验

  • 逐条把产物中的引文(引号内文本、F 编号引用、口径短语)与源文对照,检查:逐字一致 / 限定词未夸大 / 层级未拔高
  • 修补自身回验(方案 B 必做):本次修补新引入的引用同样要回验其是否真被源支撑——修补本身可能引入新的事实风险

为什么修补后要回验修补自身? 修补的动因是"某处缺引用",补引用时的直觉是"这条应该支持"——恰是最容易想当然的一步。补引后必须回源核对原文标注,才能判定修补无风险。

S4 交叉引用可达

  • 核验章节号引用("§五"是否真指该内容)、文件引用、锚点引用
  • 链接目标存在性委托 python .agents/scripts/check-links.py --path <目录>,本Skill不重复实现
  • 溯源完整性可用 check-source-traceability.py(source 字段 → 派生产物反向索引)

S5 分级发现清单与结论

级别判据
P0结论性错误(引用与源矛盾、覆盖缺失导致结论不成立)
P1重大遗漏(关键条目缺失、引用指向错误章节)
P2承诺未兑现(声明的"链接处"不存在、声明的口径与实际不符)
P3体例/引用形式不一致(纯文本引用 vs 链接、编号未随附)
  • 输出结构:检查范围与方法 → 逐项核验证据 → 发现清单 → 结论
  • 默认只报告不修改;修复须另获授权,且修复后回到 S1 复验

为什么发现要分级而不是列流水账? 未分级的清单把"引用形式不一致"和"结论不成立"并列,读者无法决定是否放行。分级把清单变成决策依据。

6. 质量门

  • G1:S1 基准全部来自磁盘原文,无一条取自记忆或摘要
  • G2:S2 为双向集合比对且全量,无抽样
  • G3:每条发现均附磁盘证据(文件 + 行号 + 原文片段)
  • G4:结论级别与发现级别一致(无 P0/P1 时不得使用"完全正确"等绝对表述)

7. 安全检查清单

  • 只读承诺:核验全程零写入(等价 dry-run);如需修复,先取得授权再单独执行
  • 幂等:重复执行同一核验,结论一致(时间/提交号类锚点除外)
  • 不擅改:发现缺陷只报告,不顺手修(修复范围须由用户批准)
  • 不越界:链接存在性转 link-check-cmd,代码重复转 check-duplication-cmd
  • 同轴证据:结论锚定与宣称同轴的证据(宣称"内容一致"就用内容比对,不用"文件存在"代替)
  • 合并后存活:核验对象若在版本控制中,确认目标提交仍为当前 HEAD 祖先

8. 执行日志(CMD-LOG)

按 CMD-LOG规范 输出:

  • cmd=artifact-consistency-audit,session 前缀 sc-YYYYMMDD-<topic>
  • 事件:AUDIT_STARTED、BASELINE_RELOADED、COVERAGE_COMPARED、CITATION_VERIFIED、FINDINGS_REPORTED
  • 覆盖率比对结果(N↔M)必须落日志,作为可复算证据

9. Gotchas(陷阱与反直觉行为)

  • 用记忆当基准:最隐蔽的失效模式——摘要里的"已完成"会被当作事实核验,得出全绿假象
  • 只看产物不看源:单向比对查不出幽灵项;必须双向
  • 只核验被修补处:修补会引入新引用,新引用也要回验(方案 B 的意义)
  • 逻辑轴冒充物理轴:以"文件存在""目录大小为零"推断"内容正确""已清理",两轴之间隔着未建模的环节
  • 发现即动手:核验与修复是两次授权;混在一起会让核验结论失去独立性
  • 抽样代替全量:抽样在小规模产物上省不了多少,却会漏掉唯一那处缺失

10. 关键参考

参考用途
link-check-cmd链接存在性检查与自动修复(本Skill的 S4 委托对象)
check-duplication-cmd代码重复检查(边界外)
ci-check-cmd提交前流水线编排(边界外)
sovereign-rollout-cmd核验后若需向主权区落盘修复,走其四阶段闭环

11. Changelog

  • v1.0.0 (2026-09-23): 初始版本。萃取自 sc-20260923 会话三次实战核验(AI 协作排除条款检查 / D1-D4 修补后复验 / TODO 完整性体检),三条纪律(双向集合比对、逐字回验、修补自身回验)均经真实缺陷命中验证。
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 193kUpdated Claude CodeCodexVerifiedInstall