Citation Diversifier (budget-as-constraints) [NO NEW FACTS]

Purpose: fix a common survey failure mode:

• the draft reads under-cited (or reuses the same few citations everywhere)

• the pipeline fails the global unique-citation gate

This skill does not change prose by itself. It produces a constraint sheet: output/CITATION_BUDGET_REPORT.md .

Inputs

• output/DRAFT.md

• outline/outline.yml (H3 ids/titles; used to allocate budgets per subsection)

• outline/writer_context_packs.jsonl (source of allowed_bibkeys_{selected,mapped,chapter,global} per H3)

• citations/ref.bib

Output

• output/CITATION_BUDGET_REPORT.md

Non-negotiables (NO NEW FACTS)

• Only propose citation keys that exist in citations/ref.bib .

• Only propose keys that are in-scope for the target H3 (prefer subsection-first scope; use chapter/global only when truly cross-cutting).

• Do not propose “padding citations” that would require adding new claims or new numbers.

What a good budget report looks like (contract)

The report should feel like a constraint sheet, not a random list:

• It states the blocking policy target and the gap-to-target (how many unique keys are missing; policy default is recommended ).

• For each H3, it proposes a scope-safe budget sized to actually close the gap:

• small gaps: 3-6 keys / H3 is often enough

• A150++ gaps: plan for ~6-12 keys / H3 (and avoid duplicates across H3 budgets)

• It gives placement guidance (where in the subsection those keys can be embedded without adding new facts).

Canonical (parseable) lines required (downstream validators depend on these):

• The target is derived from queries.md:citation_target (recommended by default for A150++).

• • Global target (policy; blocking): >= <N> ...
• • Gap: <K> (gap-to-target; if 0 , injection can be a no-op PASS)

Optional (always reported; may be blocking depending on citation_target ):

• • Global recommended target: >= <N> ...
• • Gap to recommended: <K>

Recommended prioritization (scope-safe):

• allowed_bibkeys_selected → allowed_bibkeys_mapped → allowed_bibkeys_chapter

• Use allowed_bibkeys_global only for:

• benchmarks/protocol papers

• widely-used datasets/suites

• cross-cutting surveys/method papers referenced across chapters

How this connects to writing (LLM-first)

After you generate the budget report:

• Apply it using citation-injector (LLM edits to output/DRAFT.md , NO NEW FACTS).

• Then run draft-polisher to remove any “budget dump voice” while keeping citation keys unchanged.

Important: citation-injector is LLM-first. Its script is validation-only.

Workflow

• Diagnose the global situation

• Read output/DRAFT.md and estimate the “unique-key gap” (or use pipeline-auditor ’s FAIL reason).

• Allocate budgets per H3 (scope-first)

• Use outline/outline.yml to enumerate H3s in paper order.

• For each H3, read its allowed key sets from outline/writer_context_packs.jsonl .

• Pick a small set of unused keys that strengthen positioning without requiring new claims.

• Write output/CITATION_BUDGET_REPORT.md

Required structure:

• • Status: PASS|FAIL
• • Global target (policy; blocking): >= <N> ...
• • Gap: <K>

• Summary

(gap + strategy)

• Per-subsection budgets

(H3 id/title → suggested keys → placement hint)

Script (optional; deterministic report generator)

If you want a deterministic first-pass budget report, run the helper script. Treat it as a baseline and refine the plan as needed.

Quick Start

• python .codex/skills/citation-diversifier/scripts/run.py --help

• python .codex/skills/citation-diversifier/scripts/run.py --workspace workspaces/<ws>

All Options

• --workspace <dir>

• --unit-id <U###> (optional)

• --inputs <semicolon-separated> (rare override; prefer defaults)

• --outputs <semicolon-separated> (rare override; default writes output/CITATION_BUDGET_REPORT.md )

• --checkpoint <C#> (optional)

Examples

• Default IO:

• python .codex/skills/citation-diversifier/scripts/run.py --workspace workspaces/<ws>

Done criteria

• output/CITATION_BUDGET_REPORT.md exists and has actionable, in-scope budgets.

• After applying the plan via citation-injector , pipeline-auditor no longer FAILs on global unique citations.