evidence-binder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Evidence Binder (NO PROSE)

Evidence Binder（禁止撰写散文）

Goal: convert a paper-level pool into a subsection-addressable evidence plan.

This skill is the bridge from “Evidence Bank” → “Writer”: the writer should only use evidence IDs bound to the current subsection.

Why this matters for writing quality:

Weak/undifferentiated bindings force the writer to either pad prose or cite out-of-scope.
Treat
```
binding_gaps
```
as a routing signal: fix upstream evidence/mapping instead of "writing around" missing evidence.

目标：将论文级别的证据池转换为可按小节寻址的证据计划。

该技能是连接“证据库（Evidence Bank）”与“撰稿人”的桥梁：撰稿人应仅使用绑定到当前小节的evidence ID。

这对写作质量至关重要的原因：

薄弱/无差异的绑定会迫使撰稿人要么堆砌内容，要么引用超出范围的证据。
将
```
binding_gaps
```
视为路由信号：修复上游的证据/映射问题，而非“绕开”缺失的证据进行写作。

Inputs

输入

```
outline/subsection_briefs.jsonl
```
```
outline/mapping.tsv
```
```
papers/evidence_bank.jsonl
```
Optional:
- ```
citations/ref.bib
```
  (to validate cite keys when evidence items carry citations)

```
outline/subsection_briefs.jsonl
```
```
outline/mapping.tsv
```
```
papers/evidence_bank.jsonl
```
可选：
- ```
citations/ref.bib
```
  （当证据项包含引用时，用于验证引用键）

Outputs

输出

```
outline/evidence_bindings.jsonl
```
(1 JSONL record per subsection)
```
outline/evidence_binding_report.md
```
(summary; bullets + small tables)
- Includes
```
gaps
```
  (missing required evidence fields) and
```
tag mix
```
  (selected evidence tags) so subsection-specific evidence needs are visible.

```
outline/evidence_bindings.jsonl
```
（每个小节对应一条JSONL记录）
```
outline/evidence_binding_report.md
```
（摘要；项目符号+小型表格）
- 包含
```
gaps
```
  （缺失的必填证据字段）和
```
tag mix
```
  （已选证据标签），以便清晰查看小节特定的证据需求。

Output format (

outline/evidence_bindings.jsonl

)

输出格式（

outline/evidence_bindings.jsonl

）

JSONL (one object per H3 subsection). Best-effort fields (keep deterministic):

```
sub_id
```
,
```
title
```
```
paper_ids
```
(papers in-scope for this subsection, from
```
mapping.tsv
```
)
```
mapped_bibkeys
```
(bibkeys mapped to this subsection)
```
bibkeys
```
(a selected subset to encourage subsection-first citations)
```
evidence_ids
```
(selected evidence items from
```
papers/evidence_bank.jsonl
```
)
```
evidence_counts
```
(small summary by claim_type / tag / evidence_level)
```
binding_rationale
```
(short bullets; why the selected evidence covers this subsection’s axes / desired tags)
```
binding_gaps
```
(list[str]; required evidence fields not covered by selected evidence; drives the evidence self-loop upstream)

JSONL（每个H3小节对应一个对象）。尽最大努力保留确定性字段：

```
sub_id
```
、
```
title
```
```
paper_ids
```
（该小节的关联论文，来自
```
mapping.tsv
```
）
```
mapped_bibkeys
```
（映射到该小节的引用键）
```
bibkeys
```
（精选子集，鼓励优先引用小节专属的文献）
```
evidence_ids
```
（从
```
papers/evidence_bank.jsonl
```
中选择的证据项）
```
evidence_counts
```
（按claim_type/标签/证据级别统计的小型摘要）
```
binding_rationale
```
（简短项目符号；说明所选证据为何覆盖该小节的维度/所需标签）
```
binding_gaps
```
（字符串列表；所选证据未覆盖的必填证据字段；驱动上游的证据自循环优化）

A150++ density contract (default)

A150++密度约定（默认）

Use
```
queries.md:per_subsection
```
as the width contract (A150++ default: 28).
Bind enough evidence to make writing concretely executable without out-of-scope pressure:
- ```
mapped_bibkeys
```
  : >= per_subsection
- ```
evidence_ids
```
  : >= per_subsection - 4 (A150++: >=24)
- ```
bibkeys
```
  (selected): >= 20 (so each H3 has a usable citation pool, not just a long mapped list)

使用
```
queries.md:per_subsection
```
作为宽度约定（A150++默认值：28）。
绑定足够的证据，使写作能够具体可执行，且无超出范围的压力：
- ```
mapped_bibkeys
```
  ：≥ per_subsection
- ```
evidence_ids
```
  ：≥ per_subsection - 4（A150++：≥24）
- ```
bibkeys
```
  （精选）：≥20（确保每个H3都有可用的引用池，而非冗长的映射列表）

Binding policy (how strict to be)

绑定策略（严格程度）

Subsection-first by default: the writer should primarily cite
```
bibkeys
```
and use
```
evidence_ids
```
bound to this
```
sub_id
```
.
Allow limited within-chapter reuse: citations from sibling H3s within the same H2 chapter may be reused for background/evaluation framing, but:
- keep >=3 subsection-specific citations per H3 (avoid “free cite drift”)
- avoid cross-chapter reuse unless the outline explicitly calls for it

默认优先小节专属：撰稿人应主要引用
```
bibkeys
```
并使用绑定到当前
```
sub_id
```
的
```
evidence_ids
```
。
允许有限的章节内复用：同一H2章节内的兄弟H3小节的引用可复用为背景/评估框架，但需满足：
- 每个H3至少保留3个小节专属引用（避免“无限制引用漂移”）
- 除非大纲明确要求，否则避免跨章节复用

Workflow (NO PROSE)

工作流（禁止撰写散文）

Read
```
outline/subsection_briefs.jsonl
```
to understand each H3’s scope/rq/axes.
Read
```
outline/mapping.tsv
```
to know which papers belong to each subsection.
Read
```
papers/evidence_bank.jsonl
```
and select a subsection-scoped set of
```
evidence_id
```
items per H3.
If
```
citations/ref.bib
```
exists, sanity-check that any cite keys referenced by selected evidence items are defined.

Write

outline/evidence_bindings.jsonl

and

outline/evidence_binding_report.md

读取
```
outline/subsection_briefs.jsonl
```
，了解每个H3的范围/研究问题/维度。
读取
```
outline/mapping.tsv
```
，明确每个小节对应的论文。
读取
```
papers/evidence_bank.jsonl
```
，为每个H3选择小节范围的
```
evidence_id
```
项集合。
若
```
citations/ref.bib
```
存在，检查所选证据项中引用的所有引用键是否已定义。

生成

outline/evidence_bindings.jsonl

和

outline/evidence_binding_report.md

。

Freeze policy

冻结策略

outline/evidence_bindings.refined.ok

exists, the script will not overwrite

outline/evidence_bindings.jsonl

Treat this marker as an explicit refinement/completion signal (especially in strict runs): only create it after you have checked
```
binding_gaps
```
and
```
tag mix
```
look subsection-specific.

若

outline/evidence_bindings.refined.ok

存在，脚本将不会覆盖

outline/evidence_bindings.jsonl

。

将此标记视为明确的优化/完成信号（尤其在严格运行模式下）：仅在确认
```
binding_gaps
```
和
```
tag mix
```
符合小节特定需求后，再创建该标记。

Heterogeneity sanity check (avoid recipe-like bindings)

异质性检查（避免模板化绑定）

A common hidden failure mode is mechanical uniformity: every H3 ends up with the same

claim_type

tag mix

, which hides what each subsection is actually missing and pushes the writer toward generic prose.

Before you mark bindings as refined:

Scan
```
outline/evidence_binding_report.md
```
: different H3 should show meaningfully different
```
tag mix
```
/
```
claim_type
```
balance.
If most H3 look identical, treat it as a binder smell: tighten
```
required_evidence_fields
```
, adjust selection rationale, or enrich the evidence bank, then rerun.

常见的隐性失败模式是机械统一性：每个H3最终的

claim_type

tag mix

都相同，这会掩盖每个小节实际缺失的内容，并促使撰稿人撰写通用化内容。

在标记绑定已优化前：

查看

outline/evidence_binding_report.md

：不同H3应显示出有意义的

tag mix

claim_type

差异。

若大多数H3看起来相同，则视为绑定异常：收紧
```
required_evidence_fields
```
、调整选择依据、或扩充证据库，然后重新运行。

Script

脚本

Quick Start

快速开始

python .codex/skills/evidence-binder/scripts/run.py --help

python .codex/skills/evidence-binder/scripts/run.py --workspace workspaces/<ws>

python .codex/skills/evidence-binder/scripts/run.py --help

python .codex/skills/evidence-binder/scripts/run.py --workspace workspaces/<ws>

All Options

所有选项

```
--workspace <dir>
```
: workspace root
```
--unit-id <U###>
```
: unit id (optional; for logs)
```
--inputs <semicolon-separated>
```
: override inputs (rare; prefer defaults)
```
--outputs <semicolon-separated>
```
: override outputs (rare; prefer defaults)
```
--checkpoint <C#>
```
: checkpoint id (optional; for logs)

```
--workspace <dir>
```
：工作区根目录
```
--unit-id <U###>
```
：单元ID（可选；用于日志）
```
--inputs <semicolon-separated>
```
：覆盖输入（罕见；优先使用默认值）
```
--outputs <semicolon-separated>
```
：覆盖输出（罕见；优先使用默认值）
```
--checkpoint <C#>
```
：检查点ID（可选；用于日志）

Examples

示例

Bind evidence IDs after building the evidence bank:

Ensure
```
papers/evidence_bank.jsonl
```
exists.

Run:

python .codex/skills/evidence-binder/scripts/run.py --workspace workspaces/<ws>

构建证据库后绑定evidence ID：

确保
```
papers/evidence_bank.jsonl
```
已存在。

运行：

python .codex/skills/evidence-binder/scripts/run.py --workspace workspaces/<ws>

Troubleshooting

故障排除

Issue: some subsections have too few evidence IDs

问题：部分小节的evidence ID过少

Fix:

Strengthen
```
papers/evidence_bank.jsonl
```
via
```
paper-notes
```
(more extractable evidence items).
Or broaden the mapped paper set for the subsection via
```
section-mapper
```
, then rerun binder.

修复方案：

通过
```
paper-notes
```
强化
```
papers/evidence_bank.jsonl
```
（增加可提取的证据项）。
或通过
```
section-mapper
```
扩大该小节的映射论文集合，然后重新运行绑定工具。

Issue:

binding_gaps

is non-empty (missing evidence types)

问题：

binding_gaps

非空（缺失证据类型）

What it means:

The subsection brief requires certain evidence fields (e.g., benchmarks/metrics/security/tooling), but the bound evidence items do not cover them.

Fix (self-loop upstream):

Prefer enriching
```
papers/evidence_bank.jsonl
```
/
```
papers/paper_notes.jsonl
```
for mapped papers (extract benchmark/metric/failure-mode details).
If the mapping is weak for that evidence type, expand
```
outline/mapping.tsv
```
for the subsection and rerun binder.
If the requirement is unrealistic for the subsection’s scope, revise
```
outline/subsection_briefs.jsonl:required_evidence_fields
```
and rerun binder.

含义：

小节概要要求某些证据字段（如基准/指标/安全性/工具），但绑定的证据项未覆盖这些字段。

修复方案（上游自循环优化）：

优先扩充映射论文对应的
```
papers/evidence_bank.jsonl
```
/
```
papers/paper_notes.jsonl
```
（提取基准/指标/故障模式细节）。
若该证据类型的映射较弱，扩大该小节的
```
outline/mapping.tsv
```
范围，然后重新运行绑定工具。
若该要求超出小节范围的实际情况，修改
```
outline/subsection_briefs.jsonl:required_evidence_fields
```
，然后重新运行绑定工具。

evidence-binder

Original

Translation

Evidence Binder (NO PROSE)

Evidence Binder（禁止撰写散文）

Inputs

输入

Outputs

输出

Output format (
`outline/evidence_bindings.jsonl`
)

输出格式（
`outline/evidence_bindings.jsonl`
）

A150++ density contract (default)

A150++密度约定（默认）

Binding policy (how strict to be)

绑定策略（严格程度）

Workflow (NO PROSE)

工作流（禁止撰写散文）

Freeze policy

冻结策略

Heterogeneity sanity check (avoid recipe-like bindings)

异质性检查（避免模板化绑定）

Script

脚本

Quick Start

快速开始

All Options

所有选项

Examples

示例

Troubleshooting

故障排除

Issue: some subsections have too few evidence IDs

问题：部分小节的evidence ID过少

Issue:
`binding_gaps`
is non-empty (missing evidence types)

问题：
`binding_gaps`
非空（缺失证据类型）

evidence-binder

Original

Translation

Evidence Binder (NO PROSE)

Evidence Binder（禁止撰写散文）

Inputs

输入

Outputs

输出

Output format (outline/evidence_bindings.jsonl)

输出格式（outline/evidence_bindings.jsonl）

A150++ density contract (default)

A150++密度约定（默认）

Binding policy (how strict to be)

绑定策略（严格程度）

Workflow (NO PROSE)

工作流（禁止撰写散文）

Freeze policy

冻结策略

Heterogeneity sanity check (avoid recipe-like bindings)

异质性检查（避免模板化绑定）

Script

脚本

Quick Start

快速开始

All Options

所有选项

Examples

示例

Troubleshooting

故障排除

Issue: some subsections have too few evidence IDs

问题：部分小节的evidence ID过少

Issue: binding_gaps is non-empty (missing evidence types)

问题：binding_gaps非空（缺失证据类型）

Output format (
`outline/evidence_bindings.jsonl`
)

输出格式（
`outline/evidence_bindings.jsonl`
）

Issue:
`binding_gaps`
is non-empty (missing evidence types)

问题：
`binding_gaps`
非空（缺失证据类型）