SPB Git

Repository Public Research preview

workflows.md 4.7 KB

# Workflows

# Audit report for an author

Lead with what blocks submission. Keep the registry evidence next to each item so the author can decide without rerunning anything. verify-bib --format md produces the tables; add the sections below around them.

markdown
# Reference audit: <manuscript>, <date>

Checked N entries against Crossref, arXiv and doi.org.
Verified: a. DOI found for entries without one: b. Need a decision: c.

## 1. Must be resolved before submission
- `key` — retracted (notice: <doi>, <date>). Cited in section 2 as support for <claim>.
- `key` — DOI does not exist, and no record with this title was found.
- `key` — DOI resolves to a different paper: cited "<title>", registered "<title>".

## 2. Probably typos (confirm)
- `key` — year cited 1996, registered 1986.
- `key` — DOI not found; the same title, author and year are registered as <doi>.

## 3. Could not be checked
- `key` — book, not in the registries. Please confirm from the copy you used.
- `key` — two similar records (<doi>, <doi>); which one did you read?

## 4. Proposed additions (no change of meaning)
- DOIs for b entries (diff attached).

## Not covered by this audit
- Whether each cited work supports the sentence that cites it.
- Page numbers of quotations.
- Works published or retracted after <date>.

Rules for the report:

  • One line per entry, with the citation key the author knows.
  • Quote the registry value exactly; do not paraphrase a title.
  • Separate "the registry disagrees" from "the registry does not know". They call for different actions.
  • Do not rank references by quality or citation count unless asked.
  • If an error status remains after a second run, list it under "could not be checked" with the reason.

# Applying fixes

Only after the author agrees, and one kind at a time:

  1. Add missing DOIs from suggested_doi of doi_missing_found entries. Change nothing else in the entry.
  2. Replace an entry with registry metadata (cite <doi> --style bibtex --key <same key>) when the author confirms the record is the work they mean. Keep the citation key so the text still compiles.
  3. Remove or replace a retracted or unfound reference: the author rewrites the sentence. A claim left without a source must be flagged in the text, not silently kept.

After editing, run verify-bib again on the changed keys (--keys a,b).

# Checking one claim, not one reference

A verified reference can still be misused. When a sentence relies on a specific result:

  1. get <doi> and read the abstract when the registry has one.
  2. oa <doi> for a legal open copy; read the passage.
  3. If no open copy exists, say that the claim was not checked against the text. Do not infer the content of a paper from its title.

# Literature search procedure

A search is reproducible when someone else can rerun it and understand why each work is in or out. Keep a log from the first query.

Step Command Record
Seeds resolve, search --title ... --author ... DOIs of the seed set
Keyword search search "<terms>" --from Y --to Y --type journal-article --limit 50 query, filters, date, total hits, number screened
Preprints arxiv 'abs:"<phrase>" AND cat:<category>' --sort date query, date, hits
Backward snowballing references <doi> for each included work works added
Forward snowballing citations <doi> --sort citations, then --sort date --from Y works added, total citing
Authors author --orcid <id> --sort date works added
Stop rule a full round adds nothing new number of rounds

Practical points:

  • Crossref relevance ranking favours title matches; rerun important queries with --sort citations to surface the established works, and with --sort date for recent ones.
  • Forward snowballing through highly cited seeds returns thousands of works. Narrow with --from <year> and read the most cited and the most recent pages rather than all of them.
  • Without an OpenAlex key, plan around the daily budget (references/sources.md): do the backward pass first (Crossref, free), then spend OpenAlex calls on forward citations of the few most central works.
  • Deduplicate on DOI. A preprint and its published version have different DOIs: arxiv output gives published_doi when the authors recorded it.
  • Before finalising, run retractions on the included set.

What to state in the methods section: the services searched and the date, the exact queries and filters, the snowballing rounds, inclusion and exclusion criteria, and the counts at each step. Also state that OpenAlex and Crossref were the only indexes used; databases such as Scopus, Web of Science, PubMed or EconLit may hold works these miss.

Files main
Menu

Theme