work-gaps

/work-gaps — 差距与遗漏查找器

实现完整性评审者模式——质量体系的最后一道关卡：在查找 → 去重 → 验证之后，它会询问“列表／范围本身遗漏了什么？”，并输出机器可检查的 clearedToClose 判定，供编排器据此分支处理。

适用场景

• 在一次全面检查、评审轮次或设计阶段之后，在准备宣布“完成”之前使用。
• 你希望对那些系统化流程往往会遗漏的事项进行有意而为的最后检查（忘记的模态、未经验证就假定为真的声明、未曾考虑的下游使用方）。

这是一种低成本保障，可避免出现“我们覆盖了所有重要事项”的错觉，而实际情况只是“我们覆盖了所有想到的事项”。

工作流形态 — PARALLEL / BARRIER 关卡（默认单轮）

此技能是规范 Review 框架的收尾关卡 （find → dedup → work-refute → work-gaps；参见 workflow-mode.md §2）。

• 默认：单轮评审者。 对重建出的范围运行一次评审者就足以应对大多数工作，而且相对于它所把关的工作而言，成本很低。
• 扩展方案：PARALLEL / BARRIER 扇出。 对于大型或高风险的范围，按遗漏类别扇出一个盲测子 Agent（缺失模态、未经验证的声明、下游、假设、横切问题等），各自不知道其他 Agent 的检查角度，以免它们都聚焦于相同差距。然后通过屏障收集所有结果，并在输出差距前将这些结果的并集与 SEEN 去重（所有曾发现的内容，包括验证者驳回的项目——L4）。这里采用屏障是合理的，因为存在真实的跨项目依赖：必须先对并集去重，才能做出关闭判定。

为什么采用屏障，而不是流水线：clearedToClose 关卡要基于所有类别的结果一次性做出单一判定——不能基于部分并集关闭。与 SEEN 去重这一步是纯粹的集合逻辑，绝不调用 Agent。

此技能本身不是一个 LOOP——但其 gaps[] 输出是用于启动 LOOP 的种子：每个差距都会成为另一个 work-sweep、work-refute 或研究轮次的输入（参见集成）。

用法

/work-gaps "context of what was done so far" [focus="optional extra areas"]

编排器会在自然检查点以及复杂工作的最后阶段调用此技能。

工作原理

步骤 0 — 范围覆盖差异（必需；这是发现真正问题的关键步骤）

在查找各类别的差距之前，重建实际检查过的内容集合，并将其与本应检查的范围进行比对（L5）。这是更精准的完整性检查——找出从未列入清单的内容，而不是重新检查已有内容。具体来说：

• 根据待办事项／日志／交接记录，重建实际检查集合：已阅读的文件、已检查的角度、已验证的声明、已追踪的使用方。
• 运行至少一个独立的全局预言机，且该预言机不依赖扇出清单——例如，对任务的核心实体／标识符执行全仓库范围的 grep、列出所有调用方／使用方，或对照变更集运行 git diff --name-only。目的是找出扇出清单之外的项目（这正是 grounding 案例中发现 5 个孤立文件的方法——参见anti-error-lessons.md）。
• coverageDiff = global_oracle_set − actually_swept_set。差异中的每一项都是类别为 scope-gap 且附带预言机信息的候选差距。

在输出中记录预言机命令及其结果（step0.globalOracle）。 如果无法运行任何独立的全局预言机，请明确说明——这本身就是一个覆盖差距，并会阻止 clearedToClose（因为你没有证据证明范围完整）。

步骤 1 — 重建已完成的工作

• 评审者会获得（或通过工具和待办事项／日志重建）已探索、验证或确定的内容。
• 它会收到已使用的已知模态／角度、已检查的声明、已阅读的来源等清单。这就是步骤 0 用于比对的实际检查集合。

步骤 2 — 按类别系统性排查遗漏

• 提示词要求审查者逐项检查常见遗漏类别清单（如下方的 category 枚举）：
  • modality-missing — 未使用的模态／角度
  • unverified-claim — 从未经过对抗性验证的声明或发现
  • downstream — 未追踪的下游影响／使用方
  • assumption — 从未转化为直接检查的假设
  • cross-cutting — 安全性、可观测性、多租户、错误预算、负载下的性能
  • time-based — 历史／未来状态／迁移／顺序方面的考量
  • docs-ops — 文档／运维影响
  • scope-gap — Step 0 全局预言机发现的项目（不在扇出列表中）
• 另外也要考虑难以察觉的情况（例如，“从面向公众的门户调用时会发生什么？”）。
• 在 PARALLEL / BARRIER 变体中，每个类别都由一个盲审子 Agent 负责；此处则按顺序逐项检查。

步骤 3 — 负责任地记录每个遗漏（L1 + L2 — 不要只做断言）

记录遗漏就是提出一项声明；应像对待其他声明一样审视它。在提升某项遗漏之前，尤其是 downstream、assumption 或 unverified-claim：

• 独立重新打开引用的 file:line，并根据当前源文件确认遗漏（L2）。绝不能根据记忆或引用过的证据记录“X 未处理”——必须重新阅读。记录在遗漏项中注明重新阅读的内容。
• 先尝试成本最低的预言机（L1）：测试、精确的 grep 并手动确认、类型检查、运行应用。将命令和结果写入 oracleCheck。如果预言机排除了该遗漏（结果证明已处理），则设置 oracleCheck.closedGap: true，并舍弃该遗漏（不要记录虚假遗漏）。
• 经预言机检查后仍然存在的遗漏，或没有预言机可用的遗漏，应予以记录，并记录尝试的预言机检查（closedGap: false）。

步骤 4 — 使用双向标准确定优先级（L6）

依据经验证的现实影响确定优先级，同时防范两类错误——高估非遗漏项和低估真实遗漏项：

优先级	含义
high	具体可触达 + 有害 + 当前未覆盖。必须提供 reachabilityArgument（谁通过什么路径触达它）。没有该论据，不得标为 high。
medium	合理但未经验证，或没有可用预言机来判定
low	外观问题／已有缓解措施／开发阶段的代码整洁问题

绝不要将推测性的遗漏标为 high；绝不要把可利用的遗漏埋在 low 优先级中。

步骤 5 — 计算关闭门槛（L8 证据门槛）

仅当每个 coveredCategory 都包含 ≥1 项证据——预言机结果、重新阅读的 file:line 或干净的 Step 0 范围差异——且没有未解决的 high 遗漏时，才设置 clearedToClose: true。你声称已覆盖某个类别，却无法提供证据，该类别不算已覆盖：将其列入 droppedCoverage（L7），这会阻止关闭。有关失败的审查者如何强制设置 clearedToClose: false，请参阅空值处理与关闭门槛。

结构化输出（严格契约）

严格输出一个符合此架构的 fenced ```json 块。编排器会 解析并验证它，并根据 clearedToClose 进行分支；如果输出格式错误， 会重新请求一次，然后将此次运行视为失败（参见 workflow-mode.md §3–4）。

{
  "step0": {
    "actuallySweptSet": ["src/routes/upload-handler.ts", "auth-middleware.ts", "..."],
    "globalOracle": { "command": "grep -rn 'storageTenant' src/", "result": "7 hits across 5 files; 2 not in swept set" },
    "coverageDiff": ["src/storage/handlers.ts", "migration-runner.ts"]
  },
  "gaps": [
    {
      "category": "downstream",
      "description": "storageTenant override is read in storage/handlers.ts, never traced by the review",
      "suggestedAction": "Run work-refute on the ?hostname storage path with lens 'alternative-code-path'",
      "priority": "high",
      "reachabilityArgument": "the public-facing portal hits the upload handler with attacker-controlled ?hostname, post-auth, no session binding",
      "reReadSources": ["src/storage/handlers.ts:212"],
      "oracleCheck": { "command": "grep -n 'req.query.hostname' src/storage/handlers.ts", "result": "handlers.ts:212 uses it for tenant key", "closedGap": false }
    }
  ],
  "coveredCategories": [
    { "category": "unverified-claim", "evidence": "all 6 findings carry workDone:true from work-refute" },
    { "category": "modality-missing", "evidence": "Step 0 scope-diff clean for code paths; grep returned no un-swept callers" }
  ],
  "droppedCoverage": [
    { "category": "time-based", "reason": "no migration/ordering oracle available this round; not investigated" }
  ],
  "overallAssessment": "Coverage solid on code paths but one high-priority downstream gap is open",
  "recommendation": "Run one more work-refute round on the storage path before closing",
  "clearedToClose": false
}

字段规则：

• gaps[].category ∈ modality-missing | unverified-claim | downstream | assumption | cross-cutting | time-based | docs-ops | scope-gap。
• gaps[].priority ∈ high | medium | low。当 priority 为 high 时，必须提供 reachabilityArgument。
• gaps[].reReadSources（可选）string[]：针对此缺口重新打开并独立确认的 file:line 来源（步骤 3 / L2）。对于 downstream、assumption 和 unverified-claim 缺口，强烈建议填写，因为这些缺口必须根据当前源文件确认，而非凭记忆断言。
• gaps[].oracleCheck 记录 L1 尝试：{ command, result, closedGap: boolean }。如果某个缺口的 closedGap: true，就应该已将其删除，而不是列出。
• 每个 coveredCategories[] 项都必须包含一个 evidence 字符串（oracle 结果、重新读取的 file:line，或无差异的范围差异）。没有证据的类别应放入 droppedCoverage，而不是此处（L8）。
• droppedCoverage[] 列出所有未调查的类别及其原因（L7 — 不得静默限制数量）。
• clearedToClose 是编排器据此分支的布尔值：仅当每个 coveredCategory 都有证据、没有尚未解决的 high 缺口，且步骤 0 运行了真实的全局 oracle 时，才设为 true。

执行机制

完整表格见 workflow-mode.md §3； 以下是适用于此技能的约束机制：

空值处理与关闭门槛

critic 失败、返回空结果或格式错误，并不意味着“未发现缺口”。 这会造成 静默的假阴性——一个失效的 critic 被误读为“一切正常”，导致在没有任何覆盖证据的情况下关闭任务。正确规则如下：

• critic 运行出错、超时，或返回无法解析的输出（在唯一一次允许的 重新请求之后），结果为 UNKNOWN，而非“无问题”。
• UNKNOWN 会强制设置 clearedToClose: false，并在决策记录中以具名条目 记录失败，同时通过你的 harness 的待办事项/计划 工具显示。critic 结果为 UNKNOWN 时，不得声明任务已完成。
• 在 PARALLEL / BARRIER 变体中，失效的类别子 Agent 会被 过滤掉（.filter(Boolean)）——不能将其视为“该类别没有问题”。其类别应以原因 critic-failed 放入 droppedCoverage，重新评估仍有效的类别，并记录此项剔除。 绝不能将失效的反驳者误作覆盖（L7、L8）。

其他机制

• 完整性本身就是一种质量模式：与其所把关的工作相比，成本很低。宣布完成前，先运行默认的单轮审查；只有在范围大或风险高时才启用扇出。
• 直接预言机 ≫ 专家组（L1）：第 0 步以及每个缺口的 oracleCheck 都优先选择确定性检查，而不是概率性意见。预言机能够判定的缺口，就直接判定，而非争论。
• 结构化输出：严格执行上述 JSON 契约；将其视为失败前，先验证并重新请求一次。
• 并发上限（仅限扇出变体）：以受控批次启动类别子 Agent，每批约为 min(16, cores−2)；超出部分排队。
• 预算意识：如果预算不足，明确减少扇出类别的数量，并在 droppedCoverage 中列出未运行的类别——绝不要悄悄跳过某个类别（L7）。预算压力绝不会让 clearedToClose 变为 true。
• 不设隐式上限（L7）：每个未运行的类别、未检查的角度或被丢弃的缺口，都要作为具名条目写入 droppedCoverage 和你的流程编排工具的待办事项／计划。读者必须能够分辨“已检查无问题”和“检查范围被截断”。
• 日志／阶段：通过你的流程编排工具的待办事项／计划宣布各阶段，例如“第 0 步范围差异：全局 grep，有 2 项位于已检查集合之外”“完整性审查：发现 4 个缺口，1 个高优先级缺口未解决，clearedToClose=false”。
• 反馈到循环中：它生成的 gaps[] 是下一轮 work-exhaust、另一轮 work-sweep 或针对性 work-refute 的种子。将这些种子与 SEEN 去重，而不是与幸存项去重（L4），这样被驳回的条目就不会重新进入。

示例（单轮，来自 grounding 案例）

一次引用清理扇出任务编辑了任务列表中的所有文件，并报告 “完成”。随后，work-gaps 审查作为关闭关卡运行：

• 第 0 步重建了已检查集合（任务列表中的文件），并运行了独立的全局预言机：grep -rln '<deleted-entity-id>' .。grep 返回了5 个从未出现在任务列表中的文件—— coverageDiff = 这 5 个遗漏文件。
• 每个遗漏文件都登记为一个 scope-gap 缺口，priority: high，并附上 reachabilityArgument（它们仍然导入已删除的实体 → 构建失败）， oracleCheck = grep 命中，closedGap: false。
• 由于存在未解决的 high 优先级缺口，clearedToClose: false—— 阻止关闭，并将 5 个遗漏文件反馈到一轮清理中。若采用没有第 0 步全局预言机的简单审查，仅确认“所有类别看起来都已覆盖”，就会带着这个缺陷关闭任务并将其发布出去。

集成

• 由 work 在主要阶段之后以及“任务完成”前的最终关卡调用；编排器根据 clearedToClose 决定后续流程。
• 在 work-refute 或 work-judge 之后运行效果极佳（对抗流程未能排除的问题，周围仍可能存在缺口）。
• 它的 gaps[] 会反馈给 work-sweep（新角度）、work-refute（新浮现的主张），以及 work-exhaust 的轮次结构——始终与 SEEN 去重（L4）。
• 共享模型位于 workflow-mode.md 和 anti-error-lessons.md；此技能将 L1、L2、L4、L5、L6、L7、L8 落到实际操作中。
• 也可以针对人类与 Agent 协作的输出运行。

这是性价比最高的模式之一：完成艰难的发现和验证工作后，再多花一点时间问一句：“我们的流程系统性地忽略了哪些内容？”