evidence-selfloop

证据自循环（修复 C3/C4 → 重新绑定 → 重写草稿）

触发条件与路由

• 触发条件：证据自循环、证据循环、证据缺口、绑定缺口、blocking_missing、证据自循环、证据缺口回路。

目的：让以证据为先的流水线收敛，而不写填充性文字。

此技能读取中间证据产物（简报/绑定/证据包），并生成可执行的 TODO 列表，回答以下问题：

• 哪些小节的支撑不足？
• 问题出在映射/覆盖（C2）、证据提取（C3），还是绑定/规划（C4）？
• 应按什么顺序重新运行哪些技能，才能解除高质量写作的阻碍？

输入

• outline/subsection_briefs.jsonl
• outline/evidence_bindings.jsonl（如果可用，需包含 binding_gaps / binding_rationale）
• outline/evidence_drafts.jsonl（需包含 blocking_missing、比较、评估协议、局限性）
• 可选（有助于路由）：
  • outline/evidence_binding_report.md
  • outline/anchor_sheet.jsonl
  • papers/paper_notes.jsonl
  • papers/fulltext_index.jsonl
  • queries.md

输出

• output/EVIDENCE_SELFLOOP_TODO.md（报告类；始终写入）

自循环约定（“修复证据”的含义）

• 优先修复上游证据，而不是绕开缺口来写作。
• 如果证据包含有 blocking_missing，将其视为 STOP 信号：加强笔记/全文/映射，然后重新生成证据包。
• 如果绑定结果显示 binding_gaps，将其视为 ROUTING 信号：为已映射论文补充证据库、扩大映射覆盖范围，或调整不切实际的 required_evidence_fields。

建议的最简重新运行链：

• 如果 C3 证据薄弱：pdf-text-extractor → paper-notes → evidence-binder → evidence-draft → anchor-sheet → writer-context-pack
• 如果 C2 覆盖薄弱：section-mapper → outline-refiner →（然后重新运行 C3/C4 证据技能）

工作流（仅分析）

1. 读取 queries.md（如果存在）

• 仅将其用作软配置提示（evidence_mode / draft_profile）；不得覆盖产物约定。

2. 读取 outline/subsection_briefs.jsonl

• 对每个 sub_id，记录 axes + required_evidence_fields（该小节需要哪些类型的证据）。

3. 读取 outline/evidence_bindings.jsonl

• 对每个 sub_id，列出 binding_rationale 和 binding_gaps（绑定器能够或无法从证据库中覆盖哪些内容）。

4. （可选）读取 outline/evidence_binding_report.md

• 将其用作便于人工阅读的摘要；将其视为 outline/evidence_bindings.jsonl 的视图，而非独立的事实来源。

5. 读取 outline/evidence_drafts.jsonl

• 列出 blocking_missing（STOP 信号），并检查是否缺少比较、评估协议或局限性，以免写作内容空洞。

6. （可选）读取 outline/anchor_sheet.jsonl

• 检查每个小节是否至少有几个有引文支撑的锚点（数字/评估/局限性）。

7. （可选）读取 papers/paper_notes.jsonl 和 papers/fulltext_index.jsonl

• 用它们来规划修复路径：如果证据仅来自摘要且缺少评估相关词条，优先补充笔记/全文，而不是起草正文。

报告内容

• 汇总计数：含有 blocking_missing 的小节数、含有 binding_gaps 的小节数，以及常见失败原因。
• 各小节的 TODO：让小节达到可写状态所需的最小上游修复路径（技能 + 产物）。

状态语义（解除阻塞规则）

此技能是证据质量的写作前路由器。将其 Status: 行视为解除阻塞约定：

• PASS：没有 blocking_missing，也没有 binding_gaps -> 继续进行 C5 写作（但仍需检查非阻塞的可写性问题：比较/评估/锚点不足往往预示正文空洞）。
• OK：没有 blocking_missing，但存在一些 binding_gaps -> 可以起草，但内容的具体性可能较弱；建议先修复缺口。
• FAIL：缺少输入，或存在任何 blocking_missing -> 不要写填充性文字；修复上游问题并重新运行 C3/C4。

路由矩阵（症状 -> 根本原因 -> 上游修复）

将其用作语义路由表（而非脚本检查清单）。目标是修复最早出现故障的中间产物。

症状（出现位置）	可能的根本原因	优先检查	最小上游修复链
evidence_drafts.blocking_missing: no usable citation keys	映射的论文缺少 bibkey / citations/ref.bib 中没有对应的 bibkey	papers/paper_notes.jsonl（bibkey 字段）、citations/ref.bib	C3 paper-notes（确保有 bibkey）-> C4 citation-verifier -> 重新运行 evidence-binder -> 重新运行 evidence-draft
blocking_missing: title-only evidence	检索/元数据缺少摘要（或过滤条件过严）	papers/papers_raw.jsonl 中的摘要、papers/paper_notes.jsonl 中的 evidence_level	C1 literature-engineer（补充元数据）或 C3 pdf-text-extractor（提取全文）-> 重新运行 paper-notes
blocking_missing: no evidence snippets extractable	笔记过于单薄 / 映射论文的证据库为空	papers/evidence_bank.jsonl（计数）、papers/paper_notes.jsonl	C3 paper-notes（提取更丰富的内容；尽可能优先使用全文）-> 重新运行 C4 packs
blocking_missing: no concrete evaluation tokens	笔记/证据库未提取出基准、指标或预算	papers/paper_notes.jsonl（metrics/benchmarks 字段）、outline/anchor_sheet.jsonl	C3 paper-notes（提取评估锚点）-> 重新运行 anchor-sheet + evidence-draft
evidence pack comparisons 稀少（信号：comparisons 低）	各簇缺乏可比性，或映射覆盖度过低	outline/subsection_briefs.jsonl（各簇）、outline/mapping.tsv	C2 section-mapper（提高覆盖度）或 C3 subsection-briefs（改进聚类）-> 重新运行 evidence-draft
bindings.binding_gaps 提及基准/指标/协议	绑定器找不到针对此小节、带有评估标签的证据	outline/evidence_binding_report.md（标签组合）、papers/evidence_bank.jsonl 标签	C3 paper-notes（提取标签/证据）或 C2 扩展此小节的映射 -> 重新运行 evidence-binder
binding_gaps 提及安全/威胁模型/攻击	映射集合缺少安全相关研究，或笔记缺少威胁模型细节	outline/mapping.tsv、papers/paper_notes.jsonl	C2 扩展映射（必要时添加 C1 查询）或 C3 丰富笔记 -> 重新运行 binder/packs
binding report 在各 H3 下看起来机械地一致（标签组合相同，标签差异度低）	绑定器的选择过于公式化，或证据库标签过于粗略	outline/evidence_binding_report.md（标签组合）、证据库标签	收紧 required_evidence_fields 并改进证据库标签，然后重新运行 binder；避免试图用写作来掩盖缺乏特异性的绑定

与写作者自循环的接口（避免绕过证据直接写作）

• 如果 writer-selfloop 因缺少锚点/比较而 FAIL，且相应的 writer pack 带有 pack_warnings，请停止并运行此证据自循环：这表示该小节所用的 pack 不适合写作。
• 优先在上游一次性修复证据缺口，而不是为每个 H3 添加泛泛的填充内容。

此技能不做什么

• 不会编辑 papers/*、outline/* 或 sections/*。
• 不会编造新的事实/引用。
• 不会通过更改阈值来“放宽”质量要求；它会指引你找到最早需要修复的产物。

脚本

快速开始

• uv run python .codex/skills/evidence-selfloop/scripts/run.py --workspace <workspace>

所有选项

• --workspace <dir>
• --unit-id <U###>（可选）
• --inputs <semicolon-separated>（可选覆盖项）
• --outputs <semicolon-separated>（可选覆盖项；默认写入 output/EVIDENCE_SELFLOOP_TODO.md）
• --checkpoint <C#>（可选）

示例

• 生成 C4 packs 后生成证据 TODO 列表：
  • uv run python .codex/skills/evidence-selfloop/scripts/run.py --workspace <workspace>