spec-coverage-assessment

规范覆盖度评估

对指定范围的治理程度进行有界普查，为编写规范提供前置依据。 回答 Agent 原本只能凭直觉判断的三个问题：哪些内容已有覆盖，哪些仍是盲区，以及新规范的边界应如何划定。 输出是一份可供审查的覆盖图谱；它本身不是规范、ADR，也不是受原则追踪的实体。

名称冲突——动笔前请先阅读

doctrine coverage（coverage record | verify | forget）是 需求验证证据——用于判断是否已观察到某项 REQ-NNN 得到满足。它与本技能毫无关系。不要在说明文字、提交记录或原则实体中单独将本技能的输出称为“覆盖”；务必加以限定： “规范覆盖度”“治理覆盖度”或“覆盖图谱”。不要调用 doctrine coverage 的动词来期待本技能的语义，也不要让审阅者混淆两者——它们是不同的维度（需求证明与范围相对于规范的覆盖程度），只是恰好共用了一个词。

适用边界

当目标范围是一个子系统、crate、能力或代码区域，且其现有治理情况尚不明确时，使用此技能——你还不清楚哪些规范涉及它、这些规范是否仍然有效，或新规范应如何划分。

以下情况不要使用：

• 目标规范及其边界已明确无误——直接使用 /spec-product 或 /spec-tech。
• 任务是编写或修订一份已划定范围的规范——直接使用 /spec-product / /spec-tech；本技能的输出是它们的输入，而非替代品。
• 任务是证明某项需求已满足——使用 doctrine coverage（验证证据），这属于完全不同的类型。
• 任务是全面审计整个语料库，或逐行详尽审查——本技能进行的是有界普查（见“停止条件”），而非 /inquisition 或 /audit。

停止条件

开始前，按照 /preflight 准则，先明确决定以下事项：

• 普查深度：你将检查哪些规范/ADR/策略，以查找涉及目标范围的声明（按标签、标题或关键词匹配）——除非目标范围确实覆盖整个语料库，否则不要检查整个语料库。
• 清点深度：统计模块/crate 级别的行数并列出文件，不要逐一阅读每个文件。抽查可疑模块；不要从头到尾通读。
• 最高优先级的缺口和边界建议一旦清晰且可供审查，就停止。不要穷尽所有锚点、所有未归属模块或所有相关性较弱的 ADR——那是审计，不是本技能的工作。
• 如果目标范围很小且已有充分依据，尽早说明并停止；不要为了套用方法而凭空制造缺口。

方法

1. 治理普查

列出已有治理声明涉及该范围的内容：

• 使用 doctrine spec list（按标签／标题／关键词子串匹配该范围进行筛选），再用 doctrine search "<surface keyword>"（BM25）找出未使用明显标签、但提及该范围的规范。
• 锚点搜集：在候选规范文件中对原始 TOML 搜索 [[source]] 块（rg -A2 '\[\[source\]\]' <spec-dir>/**/spec-*.toml）——这比逐个翻阅渲染后的 spec show 输出更快、更全面。缩小候选范围后，使用 doctrine spec show <ID> 抽查渲染视图。
• 标签／标题映射：将每份候选规范的 tags 和 responsibilities[]（TOML）与该范围的实际模块名称交叉比对——规范的正文可能声称某个范围（“此规范负责 X crate”），却没有任何锚点支撑；这仍算覆盖信号，但弱于有效锚点。
• ADR／策略／标准检查：使用 doctrine adr list、doctrine policy list、doctrine standard list（按子串／标签筛选），查找涉及该范围但不属于规范的治理内容——策略或 ADR 可能是某个组件唯一的治理依据。
• 可选：使用 doctrine relation census／doctrine concept-map 查看候选规范之间已有的关系——这有助于在步骤 5 中决定是否下钻／关联父级。

2. 范围清单

独立于治理声明，列出该范围的实际内容：

• 列出指定范围下的模块／crate／脚本／Web 目录（rg --files <path>，或使用标准目录列表命令）。
• 用行数统计每项规模（tokei、wc -l 或同类工具）——这将用于步骤 4 的规模因子。无需精确，掌握数量级即可。
• 记录之后划分边界时需要注意的结构分界：前端／后端是否可分离，是否存在 crate 边界，是否有明显独立的脚本族？

3. 覆盖映射——注意锚点有效性

按模块／crate／区域，将普查结果（1）与清单（2）对应起来：

• 已覆盖——有指向当前规范的有效锚点。
• 部分覆盖——标签／标题／正文提及了该项，但没有锚定；或虽有锚点，但锚点已失效（见下方注意事项）。
• 无治理覆盖——完全没有任何治理内容涉及。

锚点本身并非可靠依据——在将锚点计为覆盖之前，先确认其有效性。 锚点仅用于描述，不会强制校验：目前没有任何机制检查锚定路径是否仍然存在。实际发现，有效规范中的锚点所指向的文件路径，在代码早已迁至他处后仍然存在——规范看似“已覆盖”，实际上早已失效。每个用于判定某项“已覆盖”的锚点，都要先确认路径仍然存在（使用 test -e 或同类命令），再予以采信。此外还要注意：锚点密度与子系统规模可能呈反比（大型子系统的锚点往往更少，而不是更多——不要想当然地认为规模大就意味着覆盖充分）；数字规范目录旁的 slug 符号链接可能导致简单的递归搜索重复计数。

4. 缺口排序

按规模 × 中心性而非发现顺序，为无治理覆盖和部分覆盖的区域打分：

• 规模：步骤 2 统计的行数／文件数。
• 中心性：该区域的承载重要性——有多少其他组件依赖它、它对产品线有多核心，以及它是否位于其他规范已描述的依赖路径上。

列出最突出的几个缺口，而不是穷举所有无治理覆盖区域并逐一排序——停止条件在这里起作用。

5. 提出规范边界

对于每个排名靠前的缺口，理清并提出一种方案，而不只是指出缺口：

• 产品层级（领域 | 能力 | 功能——feature 是最低层级，也可以作为另一个功能的父级）——这是否需要新的产品意图（PRD），还是现有 PRD 已经涵盖了 原因，只缺技术规范？产品阶梯经过有意精简，比 C4 更短；不要为了让两者对应而强行增加第四层。
• C4 层级（上下文 | 容器 | 组件 | 代码），适用于任何新的技术规范——组件/容器通常是停止深入的层级；代码级属于例外（参见 /spec-tech 自身的指导），应该有充分理由，而不应作为默认选择。
• PRD 与 SPEC 的划分——修复方式是“为已有且声称涵盖此内容的规范添加锚点”（不新增实体）、在现有 PRD 下新增技术规范，还是同时新增 PRD 和技术规范（完全没有产品意图）？
• 一个规范还是多个规范——缺口是否属于一个连贯的组件，还是应沿着第 2 步发现的结构接缝拆分（例如，后端引擎与单独发布的 Web 前端通常是两个容器，而不是一个）？
• 下沉与父级位置——拟议的规范在 parent/descends_from 脉络中的位置在哪里？是现有组件的同级、现有容器的子级，还是系统上下文规范下的新容器？
• 起草来源——后续 /spec-product / /spec-tech 流程起草时应参考哪些现有 RFC、设计文档或切片历史，避免从空白开始编写？

6. 输出覆盖映射产物

将发现整理成一份便于审阅的 Markdown 产物（见下方格式），然后停止。此技能不会编写规范本身，而是将工作移交出去。

覆盖映射产物格式

# Coverage census — <surface name>

## Governance census
Specs / ADRs / policies / standards found touching the surface, with anchor
status per claim (live / stale / prose-only-no-anchor).

## Surface inventory
Modules/crates/areas with approximate size (loc/file count).

## Coverage map
Covered / partial / dark per area, with the anchor-liveness check applied —
not assumed.

## Ranked gaps
Top gaps by size × centrality, each with a one-line rationale for its rank.

## Boundary proposal
Per ranked gap: product altitude, C4 level, PRD-vs-SPEC split, one-or-several,
descent/parent placement, drafting sources.

## Out of scope / not assessed
What the bounded census deliberately did not chase down, so a reviewer knows
the edges of what was checked.

将其存放在项目运行时状态约定指定的位置（例如 .doctrine/state/）——它是起草时的临时输入，不是独立的正式实体，除非/直到为其建立了持久类型。

防护准则

• 不要未经检查路径是否存在就信任锚点——参见第 3 步。
• 不要将此任务视为完整审计；有明确范围的有限盘点，胜过无法完成的详尽盘点。请说明未检查的内容。
• 不要提出盘点结果无法支持的规范边界——边界不明确时，应将其作为 /spec-product//spec-tech 的开放问题，而不是在此猜测。
• 不要不加限定地将输出称为“覆盖”——参见名称冲突警告。
• 不要让此技能的输出悄然变成规范本身——它是经过审阅并明确移交的输入。

移交

覆盖映射产物可作为以下流程的输入：

• /spec-product——适用于任何拟议的 PRD 级缺口（缺少产品意图）。
• /spec-tech——适用于任何拟议的技术规范级缺口或锚点修复。
• 待办事项列表——如果拟议边界值得在有人采取行动前记录下来（backlog new）。

此技能的工作止于一份经过审阅的覆盖映射；它本身不会起草规范正文或需求实体。