evidence-binder
starsforks
How to install evidence-binder?
willoscar/research-units-pipeline-skills/evidence-binder
$npx -y skills add WILLOSCAR/research-units-pipeline-skills --skill evidence-binderBind addressable evidence IDs from papers/evidence_bank.jsonl to each subsection (H3), producing outline/evidence_bindings.jsonl. Trigger: evidence binder, evidence plan, section->evidence mapping, 证据绑定, evidence_id. Use when: papers/evidence_bank.jsonl exists and y
SKILL.md
| 1 | # Evidence Binder (NO PROSE) |
| 2 | |
| 3 | Goal: convert a paper-level pool into a **subsection-addressable evidence plan**. |
| 4 | |
| 5 | This skill is the bridge from “Evidence Bank” → “Writer”: the writer should only use evidence IDs bound to the current subsection. |
| 6 | |
| 7 | Why this matters for writing quality: |
| 8 | - Weak/undifferentiated bindings force the writer to either pad prose or cite out-of-scope. |
| 9 | - Treat `binding_gaps` as a routing signal: fix upstream evidence/mapping instead of "writing around" missing evidence. |
| 10 | |
| 11 | ## Inputs |
| 12 | |
| 13 | - `outline/subsection_briefs.jsonl` |
| 14 | - `outline/mapping.tsv` |
| 15 | - `papers/evidence_bank.jsonl` |
| 16 | - Optional: |
| 17 | - `citations/ref.bib` (to validate cite keys when evidence items carry citations) |
| 18 | |
| 19 | ## Outputs |
| 20 | |
| 21 | - `outline/evidence_bindings.jsonl` (1 JSONL record per subsection) |
| 22 | - `outline/evidence_binding_report.md` (summary; bullets + small tables) |
| 23 | - Includes `gaps` (missing required evidence fields) and `tag mix` (selected evidence tags) so subsection-specific evidence needs are visible. |
| 24 | |
| 25 | ## Output format (`outline/evidence_bindings.jsonl`) |
| 26 | |
| 27 | JSONL (one object per H3 subsection). Best-effort fields (keep deterministic): |
| 28 | |
| 29 | - `sub_id`, `title` |
| 30 | - `paper_ids` (papers in-scope for this subsection, from `mapping.tsv`) |
| 31 | - `mapped_bibkeys` (bibkeys mapped to this subsection) |
| 32 | - `bibkeys` (a selected subset to encourage subsection-first citations) |
| 33 | - `evidence_ids` (selected evidence items from `papers/evidence_bank.jsonl`) |
| 34 | - `evidence_counts` (small summary by claim_type / tag / evidence_level) |
| 35 | - `binding_rationale` (short bullets; why the selected evidence covers this subsection’s axes / desired tags) |
| 36 | - `binding_gaps` (list[str]; required evidence fields not covered by selected evidence; drives the evidence self-loop upstream) |
| 37 | |
| 38 | ## A150++ density contract (default) |
| 39 | |
| 40 | - Use `queries.md:per_subsection` as the width contract (A150++ default: 28). |
| 41 | - Bind enough evidence to make writing *concretely executable* without out-of-scope pressure: |
| 42 | - `mapped_bibkeys`: >= per_subsection |
| 43 | - `evidence_ids`: >= per_subsection - 4 (A150++: >=24) |
| 44 | - `bibkeys` (selected): >= 20 (so each H3 has a usable citation pool, not just a long mapped list) |
| 45 | |
| 46 | For `draft_profile=course_paper`, retain the same traceability shape at compact |
| 47 | density: 8 mapped bibkeys, at least 6 selected bibkeys, and at least 6 evidence |
| 48 | IDs from at least 4 papers per H3. |
| 49 | |
| 50 | ## Binding policy (how strict to be) |
| 51 | |
| 52 | - Subsection-first by default: the writer should primarily cite `bibkeys` and use `evidence_ids` bound to this `sub_id`. |
| 53 | - Allow limited within-chapter reuse: citations from sibling H3s within the same H2 chapter may be reused for background/evaluation framing, but: |
| 54 | - keep >=3 subsection-specific citations per H3 (avoid “free cite drift”) |
| 55 | - avoid cross-chapter reuse unless the outline explicitly calls for it |
| 56 | |
| 57 | ## Workflow (NO PROSE) |
| 58 | |
| 59 | 1. Read `outline/subsection_briefs.jsonl` to understand each H3’s scope/rq/axes. |
| 60 | 2. Read `outline/mapping.tsv` to know which papers belong to each subsection. |
| 61 | 3. Read `papers/evidence_bank.jsonl` and select a subsection-scoped set of `evidence_id` items per H3. |
| 62 | 4. If `citations/ref.bib` exists, sanity-check that any cite keys referenced by selected evidence items are defined. |
| 63 | 5. Write `outline/evidence_bindings.jsonl` and `outline/evidence_binding_report.md`. |
| 64 | |
| 65 | ## Freeze policy |
| 66 | |
| 67 | - If `outline/evidence_bindings.refined.ok` exists, the script will not overwrite `outline/evidence_bindings.jsonl`. |
| 68 | - 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. |
| 69 | |
| 70 | ## Heterogeneity sanity check (avoid recipe-like bindings) |
| 71 | |
| 72 | 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. |
| 73 | |
| 74 | Before you mark bindings as refined: |
| 75 | - Scan `outline/evidence_binding_report.md`: different H3 should show meaningfully different `tag mix` / `claim_type` balance. |
| 76 | - 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. |
| 77 | |
| 78 | ## Script |
| 79 | |
| 80 | ### Quick Start |
| 81 | |
| 82 | - `uv run python .codex/skills/evidence-binder/scripts/run.py --help` |
| 83 | - `uv run python .codex/skills/evidence-binder/scripts/run.py --workspace <workspace>` |
| 84 | |
| 85 | ### All Options |
| 86 | |
| 87 | - `--workspace <dir>`: workspace root |
| 88 | - `--unit-id <U###>`: unit id (optional; for logs) |
| 89 | - `--inputs <semicolon-separated>`: override inputs (rare; prefer defaults) |
| 90 | - `-- |
People who liked this also viewed
6 picksType
- tddSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
- test-driven-developmentUse when implementing any feature or bugfix, before writing implementation codeSkillsJul 2026
- qaSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
- verification-before-completionUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidenceSkillsJul 2026
- webapp-testingToolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser lSkillsJul 2026
- playwright-best-practicesUse when writing Playwright tests, fixing flaky tests, debugging failures, implementing Page Object Model, configuring CI/CD, optimizing performance, mocking APIs, handling authentication or OAuth, teSkillsJul 2026
