| name | citation-diversifier |
| description | Raise citation diversity/density (NO NEW FACTS): generate an in-scope “citation budget” plan per H3 so drafts stop failing the global unique-citation gate and stop looking under-cited.
**Trigger**: cite boost, citation budget, unique citations too low, add more citations, improve reference density, 引用太少, 增加引用, 引用密度.
|
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.mdoutline/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
course_paper: cap suggestions at 3-6 keys / H3 and target the profile's 24/32 global budget- 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
uv run python .codex/skills/citation-diversifier/scripts/run.py --helpuv run python .codex/skills/citation-diversifier/scripts/run.py --workspace <workspace>
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:
uv run python .codex/skills/citation-diversifier/scripts/run.py --workspace <workspace>
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.
