导读

在编码代理（coding agent）开工之前，任务涉及的代码里往往埋着"双方都不知道该问什么"的陷阱——错误默认值、过期冗余、过滤坏行、转义毁输出。本文基于当前仓库 explore-unknowns 技能的第四阶段参考文档（stage-4-unknown-unknowns.md），完整讲解"未知之未知（Unknown Unknowns）"扫雷流程：如何全覆盖清扫任务触及的每个文件、如何把每条发现做成带证据的地雷卡片、以及如何用盲点通行证（Blindspot Pass）把发现装配成一条更优的实现提示词。读完你即可在 jevgrep 检索得到的源码上下文上，独立执行一次系统性的任务前排雷，并把结果落进四象限地图。

背景：Stage 4 在象限走查中的位置

explore-unknowns 技能把一次任务的未知面拆成四象限，按顺序逐个走查，共五个阶段（见 SKILL.md）：

1. Known knowns—— 先扫描领域，以既定事实开场；
2. Known unknowns—— 你能命名的疑问，逐个解决；
3. Unknown knowns—— 提取从未被说出口的直觉与隐性上下文；
4. Unknown unknowns（本阶段）—— 清扫领域，猎杀地雷；
5. Hand over the map—— 交出完整的四象限地图，这是本次走查唯一的"完成"条件。

正如 SKILL.md 开篇所强调："地图不是领域本身。提示词、计划与上下文窗口是地图；代码库、领域与用户的真实意图才是领域。"未知之未知正是地图与领域之间那条最危险的缝隙——写在代码前发现的未知，代价是几分钟；三个 PR 之后才发现同一个未知，代价就是那三个 PR。

Stage 4 解决的正是"双方都不知道该问什么"的那一类问题：你无法直接提问，因为问题本身还没有成型——领域（代码）往往替你们提问。这一阶段的职责就是把任务将要触及的代码清扫一遍，把静默的陷阱转化为地图条目。

完整流程：从全覆盖清扫到地图落账

第一步：清扫任务触及的每一个文件

进入 Stage 4 后，首要动作是清扫任务将触及的每个文件，并且在开场时明确陈述覆盖范围，例如："本次清扫覆盖了本任务触及的 N 个文件"（the sweep covered the N files this task touches）。覆盖声明是硬要求：它让用户（以及接手的人）清楚知道这次排雷到底扫过多大的地，未扫到的区域本身就是一条风险记录。

清扫时要主动猎杀四类目标：

1. 地雷（Landmines）——会静默咬人的东西，文档中列出的典型形态包括：

• 错误默认值（wrong-by-default data）：某个数据结构或参数以错误的取值作为默认，代码"正常"运行但结果从一开始就是错的；
• 过期冗余（stale denormalizations）：本应保持一致的冗余数据在多次更新后漂移，读到的已经不是最新事实；
• 过滤掉坏行（filters that pass bad rows）：本意是过滤脏数据的条件，反而把坏行放行，或把好行误杀；
• 转义损坏输出（escaping that corrupts output）：字符串转义不完整或被双重转义，导致输出的内容在下一环被错误解析。

2. 未成文的约定（Unwritten conventions）——代码在强制执行、但没有任何文档记载的规则。这类约定一旦被任务改动无意破坏，往往表现为"为什么别的模块不这么写也能跑？"式的诡异回归。清扫时的任务是把它们显式化，变成地图上的一行条目。

3. 半成品或被回退的先前尝试（Half-built or reverted prior attempts）——同一个目标过去已经有人动过手：留下半截实现、或整体回退。清扫不仅要找到它们，更要查明它们"为什么死掉"——那个死因通常就是你的地雷。如果先前尝试死于某个数据假设、某个性能瓶颈或某个集成点，而新任务没有意识到，几乎必然会在同一处再次引爆。

4. 超出本功能的发现（Findings beyond the feature）——任务代码路径会继承的潜伏缺陷。它们不在任务范围内，但会顺着本次改动被触发或放大。文档给出的处理原则很明确：把它们升级到地图上，而不是静默吸收（escalate them to the map rather than silently absorbing them）。宁可多一条地图条目，也不要让一个已知的潜伏 bug 假装不存在。

第二步：把每条发现上报为卡片

每条发现都要上报为一张卡片，卡片必须包含三个要素：

• 证据（evidence）：具体的文件与行号，让任何接手者可以独立复验；
• 为什么它会咬人（why it bites）：在什么触发条件下会产生什么错误行为；
• 它改变了任务的什么（what it changes）：这条发现对当前任务计划、方案或预期结果的影响。

上报顺序有硬性要求：最严重的排最前（worst first）。这样即便对话被截断、或用户只能读完前几条，最致命的风险也一定已被看到。

第三步：按性质分流处理

发现按是否需要用户决策分为两类，处理路径不同：

• 需要用户拍板的发现：按 Stage 2 的问题关闭方式处理——给出带字母编号的选项（lettered options），并附上你的推荐（recommendation），让用户用几个字符就能回答。相关机制可参考 stage-2-known-unknowns.md 中的"采访式"提问法：一次一个问题、按架构爆炸半径排序、每个都带推荐答案。
• 只需要知情即可的发现：直接作为"锐边（sharp edge）"记录到地图上，无需打断用户决策流。

全局规则：发现即披露，不为阶段留档

SKILL.md 有一条贯穿所有阶段的铁律："阶段为走查排序，但绝不禁止信息发布"（Stages order the walk; they never embargo information）。任何实质影响在途决策（decision in flight）的发现，必须在发现的那一刻就披露，然后归档到地图对应象限下——绝不能扣住不放，留到本阶段"轮值"时才讲。SKILL.md 还规定了配套规则："任何地图记录为 closed 的问题/判断，都必须先展示给用户——包括领域已经给出答案的那些"（nothing closes off-screen）。因此本阶段的意义是系统性、全覆盖的清扫，而不是披露的起点。

完成条件（Done When）

本阶段结束必须同时满足两个条件：

1. 清扫已覆盖任务将触及的代码；
2. 每一条发现都已落到地图上——以三种状态之一存在：已决策（decided）、挂起（OPEN）、或已标注为锐边（sharp edge）。

没有任何"清扫完成但发现还躺在聊天记录里"的中间态。开放性内容（OPEN）必须写明"什么能解锁它"（what unblocks it），例如缺一个用户选择、缺一次实验验证、或需要等某个外部输入。

核心技术：盲点通行证（Blindspot Pass）

本阶段唯一的专属技术，是为反应而打包的清扫产物（the sweep packaged for reaction）。盲点通行证由三部分组成：

1. 地雷卡片集：每条卡片都带证据（文件与行号）、咬人原因，以及一条可直接复制的提示词修复（a copyable prompt fix）——即"如果采纳这条修复，提示词里应该怎么写"的现成文本；
2. 一条更优的实现提示词：把全部地雷卡片的修复整合成一条更好的实现提示词（one better implementation prompt），作为本阶段产出的总结与交付物；
3. 反应式交互：延续 SKILL.md 的两条通用心法——"反应优于想象"（Reacting beats imagining）与"每个工件都装配用户的回复"（Every artifact assembles the reply）。盲点通行证让用户的下一步动作变成"复制、粘贴、微调"而不是从零组织语言。

这套设计的目的很明确：地雷发现本身不是终点，把它们转译成用户可以直接使用的更优提示词，才算完成闭环。用户对盲点通行证的反应，应当成为他们的下一条消息——近乎零打字成本。

地图落地：Stage 5 与走查之后的延续

Stage 4 的产出最终会汇入 Stage 5 的四象限地图工件（见 stage-5-hand-over-the-map.md）：未知之未知象限中陈列的就是本阶段的地雷卡片，每张标注 decided / OPEN / sharp-edge 三态之一；需要用户在编码前确认的小事实单独成列表，作为地图条目而不是脚注。

走查结束不等于排雷结束。规划之后的三个动作在 after-the-walk.md 中有完整定义：

• 实现期笔记：构建过程中，每当代码迫使你偏离计划，记录"计划说了什么、代码揭示了什么、做了什么保守决定"；每次偏离都是一个逃过走查的未知之未知，要折回地图，供第二次尝试使用；
• 合并前买断文档（buy-in doc）：把原型、规格与笔记打包成一份可速读的陈述，用演示开场、用证据预答每位评审者的异议；
• 合并前测验（quiz before merge）：产出合并就绪报告——心智模型、引入的非显然行为、部署后要观察什么——以用户必须通过的测验收尾，答错指向他们跳过的章节。

在本仓库中的实际应用场景

本仓库的核心产品是 jevgrep（jg），一个面向编码代理的 CLI：输入自然语言问题，jg返回相关文件、阅读线索与逐字源码摘录，供代理实现与测试改动（见 README.md）。其配套的 jevgrep 技能 给出了代理侧的标准用法：

jg "How are telemetry events recorded and sent?" .

Stage 4 扫雷在这个工作流中的价值正是文档开头那句"地图不是领域"的直接落地：jg检索结果只是地图（相关文件清单与摘录），真正的领域是这些文件内部的实现细节。代理拿着检索到的源码上下文开工前，先按本文流程清扫一遍任务触及的文件——核对默认值、冗余、过滤与转义四处高发雷区，查明是否有半成品或回退的先前尝试，把超出功能的潜伏缺陷升级为地图条目——就能把"三个 PR 之后才引爆"的成本，压缩到"写代码前的几分钟"。

一个值得注意的边界：仓库源码、测试与配置都能支撑技术结论，但本阶段参考文档本身是一条流程方法论而非代码实现——它没有对应的可执行脚本，其"事实依据"在于 explore-unknowns 技能的完整框架（SKILL.md 中的规则段）、其余阶段文档的相互印证，以及 jevgrep 技能描述的代理工作流。在使用时也应遵循该技能文档自身的约束："关于领域的论断必须引用真正读过的真实文件；虚构的数据必须如实标注"（claims about the territory cite real files actually read）。

小结：一张可执行的 Stage 4 检查清单

把这份清单与四象限地图一并交给实现者，正是 Stage 4 文档与 explore-unknowns 技能框架留给代理工作流最实用的遗产：排雷不是靠运气，而是靠一次有证据、有顺序、有产物的系统性清扫。