# Validator "未知规模扫描收敛" Skill——详细设计（SDD）

**日期**: 2026-08-06
**性质**: 详细设计，对应需求文档 `docs/done/validator-loop-until-dry-skill-requirements.md`（条目 B，已确认）。回答该需求文档第 8 节的开放问题。
**状态**: 设计草案，实施中。

## 1. 范围确认：纯 Skill，不动执行引擎

跟 E/F/G 不同，这条不涉及 `work_graph_orchestrate.py`/`work_node_run.py` 任何一行代码——需求文档第 1 节的"关键澄清"已经说清楚：收敛循环发生在**一次 Work Node 执行内部**（一次 `claude -p` 会话自己的多轮工具调用），不是 `graph_manifest` 层面的图内回路。所以本轮改动只有三处：新增一个 Skill 文件、`agent_profile.py::FRONTMATTER["validator"]["skills"]` 加一行、`agents/validator/AGENTS.md` 加一段触发指引。

## 2. 开放问题的最终决定

- **Skill 命名**：`unknown-scope-defect-sweep`（需求文档 FR-1 自己给出的暂定名，评审后确认沿用，语义准确，不需要改）。目录 `skills/unknown-scope-defect-sweep/SKILL.md`，与 `qa-task-validation` 平级。**不**照抄 `qa-task-validation/SKILL.md` 里遗留的飞书 Base 内容（约束第 1 条已经点名），按 graphlemon 现有的 `task`/`bug_record` 结构化存储来写。
- **FR-3 接线方式**：每个候选项复用 `qa-task-validation` 已经定义的 PASS/FAIL/INCONCLUSIVE 判定框架（同一次会话里 Validator 已经加载了这个 Skill，直接引用它的判定原则，不重新发明一套），**不**接 `root_cause_trace` 的三视角评审团机制——`root_cause_trace`/`judge_root_cause_via_work_graph`（F）解决的是"验证失败后，根因属于 planning/coder/skill_defect 哪一类"，是验证**之后**的归因步骤；这里要解决的是"扫描出的候选项本身是不是真缺陷"，是验证**本身**，两者是流水线上不同阶段，不应该混用。
- **K 值/硬上限**：K=2（连续 2 轮无新发现即停止，需求文档背景部分引用的 14 步版建议值，也是 FR-1 自己写的参考值）。硬上限：**20 轮**——这完全是提示词层面的自我计数（一次 `claude -p` 会话内部没有 graphlemon 代码能从外部数轮次），保守值，风险第 2 条已经承认第一版数字要靠实测校准，不是理论推导出来的精确值。触达硬上限时 Skill 要求如实报告"可能未收敛"，不能假装已经扫完。
- **AGENTS.md 触发条件**：关键词信号（任务描述含"扫描/审计/全部/所有/系统性/未知规模"这类无边界表述）+ 一条更本质的判断标准（"这个任务在开始前能不能说清楚验收对象的确切数量或边界"——数不清就该用这个 Skill，能数清就走默认单轮验证），写进 `AGENTS.md`"必须加载"一节。

## 3. 去重键（FR-2）——不绑定具体场景

Skill 不规定"用文件路径"还是"用函数名"这类具体键，而是给一条通用原则：去重键必须是候选项的**结构性标识**（能唯一定位这个候选项在代码/系统里的位置——文件路径+行号、路由路径、依赖包名之类），不能用候选项的**自然语言描述**做键（同一个真实缺陷，模型两次描述的措辞很可能不完全一样，用文本做键会导致同一个候选项被误判成"新发现"）。

## 4. 唯一可测的代码触点

FR-4 的 `agent_profile.py::FRONTMATTER["validator"]["skills"]` 追加 + `deploy_agent_definitions()` 渲染进 `.claude/agents/validator.md` 的 `skills:` frontmatter——这是本轮唯一有确定性代码行为、可以用现有 `test_agent_profile.py` 模式写单测的部分（验收标准 4）。验收标准 1-3（真的能找全 5 处缺陷、真的能正确去重收敛、真的能在硬上限强制停止）依赖真实 `claude -p` 多轮工具调用行为，只能用 `RUN_REAL_AGENT_E2E=1` 真实验证，不在本轮 mock 测试范围内——这跟 F 设计文档第 6 节"视角节点并发时间收益的实测"是同一类限制，如实记录，不假装 mock 测试能替代它。