Citations

What’s inside

• Skills
• skills/citations/SKILL.mdcitations · 4.7 KBUse when the user wants to add a paper to their references (from a link, DOI, arXiv id or title), fix or tidy a .bib file or References section, merge duplicate entries, or find a source for a sentence. Every entry comes from a real record, never from memory.

  ---
  name: citations
  description: >
    Use when the user wants to add a paper to their references (from a link,
    DOI, arXiv id or title), fix or tidy a .bib file or References section,
    merge duplicate entries, or find a source for a sentence. Every entry comes
    from a real record, never from memory.
  ---
  
  # Citations
  
  Citations looks after one reference list: the `.bib` file the documents
  cite, or a References section in a markdown doc. It does three jobs: add a
  source, tidy the list, and find a source for a sentence.
  
  ## Find the list
  
  1. In LaTeX, follow `\bibliography{...}` or `\addbibresource{...}` in the
     main `.tex`. In markdown, the `bibliography:` front matter, else the doc's
     References heading.
  2. Otherwise `Glob` for `**/*.bib`. One file: use it. Several: ask which.
  3. None yet: for LaTeX, create `references.bib` beside the main `.tex` and
     add `\bibliography{references}` before `\end{document}` (with a
     `\bibliographystyle{plain}` if the file has no style and no biblatex).
     For markdown, add a `## References` section with footnotes `[^key]`. The
     editor does not render pandoc `[@key]` citations, so never use them.
  
  Read the whole list before changing it. Match its key style (most often
  `surnameYEARword`, e.g. `vaswani2017attention`), its field order and its
  brace or quote style.
  
  ## Get the real record
  
  The web tools cannot ask for BibTeX, so fetch records with `curl` in Bash.
  Send one request at a time with `-A "Sundial-Citations (https://sundial.md)"`.
  Never put the user's name or email in a request.
  
  - **DOI** (from `https://doi.org/...`, `doi:` or a publisher page): strip the
    prefix, then
    `curl -sL -H "Accept: application/x-bibtex" "https://doi.org/<doi>"`.
    This works for Crossref and DataCite DOIs. If it fails, try
    `https://api.crossref.org/works/<doi>/transform/application/x-bibtex`.
  - **arXiv** (an `abs/` or `pdf/` link, or `arXiv:<id>`): drop the `vN`
    suffix, then `curl -s "https://export.arxiv.org/api/query?id_list=<id>"`.
    If the feed has `<arxiv:doi>`, the paper was published: fetch that DOI's
    record instead and keep `eprint = {<id>}` and `archivePrefix = {arXiv}`.
    Otherwise build an `@misc` entry from the feed's title, authors and year.
    Wait 3 seconds between arXiv requests.
  - **Title or a pasted reference**: URL-encode it, then
    `curl -s "https://api.crossref.org/works?query.bibliographic=<text>&rows=5"`.
    Accept a hit only when its title, first author and year all match. If
    none or several match, list the candidates and pick none.
  - **Status**: `curl -s "https://api.crossref.org/works/<doi>"`. An
    `update-to` or `relation` naming a retraction or correction goes in your
    reply as a warning.
  
  ## Write the entry
  
  - Rename the fetched key to the list's style. Keep a key the documents
    already cite.
  - Keep every author the record names. Never shorten to `and others`.
  - Protect capitals that must stay in titles with braces: `{BERT}`, `{Lean}`.
  - A field no record confirms stays out, with `% TODO: <field>` above the
    entry. Never fill one in from memory.
  - Add the entry with `Edit`, so the change shows up as a reviewable edit.
    Say the key in your reply, and where to cite it (`\cite{key}`, or `[^key]`
    in markdown). Insert the citation into a document only when asked.
  
  ## Tidy the list
  
  Report what you find, then fix it as edits:
  
  - **Same key twice**: the editor keeps only the first, so the other one
    quietly disappears from `\cite` suggestions.
    `grep -oiE '^@[a-z]+\{[^,]+' <file>.bib | sort | uniq -d`
  - **Same paper under two keys** (same DOI or arXiv id): merge into the key
    the documents cite most, and update the other key's `\cite`s.
    `grep -oiE 'doi *= *[{"][^}"]+' <file>.bib | tr A-Z a-z | sort | uniq -d`
  - **Cited but missing**: a `\cite` key with no entry. Find the paper and add
    it, or list it if you can't be sure which paper it is.
  - **Broken entries**: missing authors, year or venue, mangled characters, a
    DOI written as a full URL in `doi`.
  - **Preprints since published**: upgrade them, keeping the arXiv id.
  - **Unused entries**: list them. Delete only when asked.
  
  Never run `bibtex` or `biber` in Bash. Making the PDF runs them, and its log
  shows any bibliography errors.
  
  ## Find a source for a sentence
  
  1. Search with `web_search` and with the Crossref query above, using two or
     three phrasings of the sentence's claim.
  2. Open the paper's own abstract or full text and confirm it says what the
     sentence says. Never cite from a search snippet.
  3. Answer in chat: the paper, one line on what it shows, and its entry ready
     to add. Add it to the list and cite it only when the user says so.
  4. Nothing fits? Say exactly that. A shorter honest list beats a made-up
     source. Whether a source really backs a claim is the Claim Verifier
     module's job; suggest it when the user asks.