| name | citation-injector |
| description | Apply a `citation-diversifier` budget report by injecting *in-scope* citations into an existing draft (NO NEW FACTS), so the run passes the global unique-citation gate without citation dumps.
**Trigger**: citation injector, apply citation budget, inject citations, add citations safely, 引用注入, 按预算加引用, 引用增密.
**Use when**: `output/CITATION_BUDGET_REPORT.md` exists and you need to raise *global* unique citations (or reduce over-reuse) before `draft-polisher` / `pipeline-auditor`.
**Skip if**: you need more papers/citations upstream (fix C1/C2 mapping first), or `citations/ref.bib` is missing.
**Network**: none.
**Guardrail**: NO NEW FACTS; do not invent citations; only inject keys present in `citations/ref.bib`; keep injected citations within each H3’s allowed scope (via the budget report); avoid citation-dump paragraphs (embed cites per work).
|
Citation Injector (deterministic baseline edits; budget-as-constraints)
Purpose: make the pipeline converge when the draft is:
- locally citation-dense but globally under-cited (too few unique keys), or
- overly reusing the same citations across many subsections.
This skill is intentionally conservative and scriptable:
- the script edits
output/DRAFT.md directly using the budget report as constraints
- injections stay evidence-neutral (NO NEW FACTS) and use only in-scope keys already listed for each H3
Inputs
output/DRAFT.mdoutput/CITATION_BUDGET_REPORT.md (from citation-diversifier)outline/outline.yml (H3 id/title mapping)citations/ref.bib (must contain every injected key)
Outputs
output/DRAFT.md (updated in place)output/CITATION_INJECTION_REPORT.md (PASS/FAIL + what you changed)
Non-negotiables (NO NEW FACTS)
- Only inject keys listed for that H3 in the budget report.
- Do not introduce new numbers, new benchmarks, or superiority claims.
- Do not add narration templates such as
This subsection discusses or Next, we examine.
- Do not produce cite dumps like
[@a; @b; @c] as the only citations in a paragraph.
Paper-voice injection patterns (safe sentence shapes)
Use these as sentence intentions (paraphrase; do not copy verbatim).
- Axis-anchored exemplars (preferred)
Systems such as X [@a] and Y [@b] instantiate <axis/design point>, whereas Z [@c] explores a contrasting point under a different protocol.
- Parenthetical grounding (short, low-risk)
The same design pressure appears in nearby systems (e.g., X [@a], Y [@b], Z [@c]).
- Cluster pointer + contrast hint
Representative implementations span both <cluster A> (X [@a], Y [@b]) and <cluster B> (Z [@c]), suggesting that the trade-off hinges on <lens>.
- Decision-lens pointer
For builders choosing between <A> and <B>, prior systems provide concrete instantiations on both sides (X [@a]; Y [@b]; Z [@c]).
- Evaluation-lens pointer (still evidence-neutral)
Across commonly used agent evaluations, systems such as X [@a] and Y [@b] illustrate how <lens> is operationalized, while Z [@c] highlights a different constraint.
- Contrast without list voice
While many works operationalize <topic> via <mechanism> (X [@a]; Y [@b]), others treat it as <alternative> (Z [@c]), which changes the failure modes discussed later.
Anti-patterns (high-signal “budget dump” voice)
Avoid these stems (they read like automated injection):
A few representative references includeNotable lines of work includeConcrete examples include
If your draft contains these, rewrite them immediately using the patterns above (keep citation keys unchanged).
Placement guidance
- Prefer inserting citations where the subsection already states a concrete contrast or decision lens.
- If you must add a new sentence/mini-paragraph, place it early (often after paragraph 1) so it reads as positioning, not as an afterthought.
- Keep injections subsection-specific: mention the subsection lens (H3 title /
contrast_hook) so the same sentence cannot be copy-pasted into every H3.
Workflow
- Read the budget report (
output/CITATION_BUDGET_REPORT.md)
- Treat
Global target (policy; blocking) as the PASS line for the pipeline gate (derived from queries.md:citation_target; A150++ default: recommended).
- If
Gap: 0, do nothing: write a short PASS report and move on.
- Otherwise, for each H3 with suggested keys, pick enough keys to close the gap to target:
- small gaps: 3-6 keys / H3
- A150++ gaps: often 6-12 keys / H3
Prefer keys that are unused globally and avoid repeating the same new keys across many H3s.
- Inject in the right subsection
- Use
outline/outline.yml to confirm H3 ordering and ensure the injected sentence lands inside the correct ### subsection.
- Inject with paper voice
- Prefer one short, axis-anchored sentence over a long enumerator sentence.
- Keep injections evidence-neutral (NO NEW FACTS) and avoid new numbers.
- Before you commit an injected key, confirm it exists in
citations/ref.bib.
- Write
output/CITATION_INJECTION_REPORT.md
- Record which H3s you touched and which keys were added.
- Mark
- Status: PASS only when the global target is met.
- Verify
- Rerun the validator script (below) to recheck the global target.
- Then run
draft-polisher to smooth any residual injection voice (citation keys must remain unchanged).
Done criteria
output/CITATION_INJECTION_REPORT.md exists and is - Status: PASS.pipeline-auditor no longer FAILs on “unique citations too low”.
Script (optional; deterministic injector + validator)
You usually do not run this manually; it exists so a pipeline runner can deterministically apply a baseline injection and validate the target.
Quick Start
uv run python .codex/skills/citation-injector/scripts/run.py --workspace <workspace>
All Options
--workspace <dir>--unit-id <U###> (optional; for logs)--inputs <semicolon-separated> (rare override; prefer defaults)--outputs <semicolon-separated> (rare override; default validates output/CITATION_INJECTION_REPORT.md)--checkpoint <C#> (optional)
Examples
- After you generate the budget report and want the script to apply the baseline injection:
uv run python .codex/skills/citation-injector/scripts/run.py --workspace <workspace>
