grounded-citations

Grounded citations

Glossary: unfamiliar with BBT, MCP, DOI? See skills/_glossary.md for one-line definitions of every acronym this skill uses.

Insertion vs verification. This skill governs inserting a citation during drafting — it can drop a claim if no source supports it. The audit-time counterpart is verifying-citations (loaded by fact-check and by critic-loop's evidence critic), which decides whether an existing @citekey in a manuscript is honestly supported by its source. Both demand externalised consultation; their escalation triggers differ: grounded-citations escalates on recency / context staling (a Zotero child note beats a faded context-window memory); verifying-citations escalates on claim type (a quoted passage or specific β always requires the full text, regardless of how the abstract reads). Same goal, different decision axis.

Bootstrap (first run in this project)

Before applying the rules below, check that this skill's regression tests are installed in the project:

python3 "${CLAUDE_PLUGIN_ROOT:-.}/scripts/setup/check_project_scaffold.py" \
    scripts/test_common.py scripts/test_citations.py

If the output lists missing files, install them:

python3 "${CLAUDE_PLUGIN_ROOT:-.}/scripts/setup/install_templates.py" \
    test_common.py:scripts/test_common.py \
    test_citations.py:scripts/test_citations.py

Then tell the user what was installed and flag that the top of scripts/test_citations.py has project-specific paths (manuscript, references.bib, optional coded_papers.csv) they should review.

Core rule

Every citation the agent inserts into academic prose must satisfy all four of these requirements. They are conjunctive — failing any one means the citation may not be made.

1. In Zotero. The paper is in the project's Zotero library. If not, add it via mcp__zotero__zotero_add_item (source_type="doi", or "url" when no DOI exists) before the citation is written.
2. BBT key. The [@citekey] in prose is the Better BibTeX key fetched from Zotero via mcp__zotero__zotero_get_item_metadata with format="bibtex". Never hand-craft keys (Smith2019-style); never fabricate; never write to Zotero's Extra field to pin a key.
3. Externalised consultation. At citation time, the paper's content is available either as a fresh MCP response (abstract, notes, or full-text retrieved in the current turn or an adjacent recent turn) or as a Zotero child note read via mcp__zotero__zotero_get_notes. Context-window recall alone is not sufficient: remembering an abstract read 500K tokens ago is not grounding — either re-fetch it or read the note. Operational rule: if the abstract or fulltext was read more than ~5 conversational turns ago, or if context has been compacted in between, re-fetch via MCP or read the stored Zotero note. The boundary is "could the same words still be in your working context"; when in doubt, re-fetch.
4. Claim support. The consulted content visibly supports the attributed claim. If nothing you have consulted supports the claim, drop the claim. Do not paper over; do not flag for later; do not keep a speculative citation. Remove it from prose, or replace the attribution with a source that does support the claim.