05bdff6e68
Codex chapter-by-chapter audit findings applied across vol1 and vol2:
prose rewrites where the cited source supported only a narrower or
adjacent claim, plus new audit tooling
(book/tools/scripts/build_citation_reference_packets.py and the
companion workflow doc).
Author-form cleanup pass on top of the audit:
- 19 narrative @key conversions where prose already named the author
(e.g., "Sambasivan et al. describe ... [@sambasivan2021]" -> narrative
"@sambasivan2021 describe ...", rendering "Sambasivan et al. (2021)
describe ...") - removes the citeproc duplication that the
manual-bracket regex did not catch.
- 4 [-@key] suppressed-author conversions for possessive eponyms
(Han et al., Vaswani et al., Patarasuk and Yuan, Linnainmaa).
- 2 [-@key] conversions where the prose names an author/entity that
matches the cited author (Patterson and Hennessy's iron law,
Google's data centers + Google whitepaper).
- 1 Horowitz footnote rewritten to narrative so the inline year
replaces a duplicated "(ISSCC 2014, ...) (Horowitz 2014)" pair.
- 1 narrative @russell2021 anchoring "As Russell argues" that was
previously a bare attribution.
- 1 pre-existing narrative fix for "Graham et al. report ..." in
collective_communication that had no cite on the line.
Pre-commit cleanups landing with this commit:
- subramanya2019diskann: add publisher = Curran Associates (NeurIPS
proceedings, per bib-check rule 3).
- Remove orphaned @misc{Wu2016} GNMT bib entry in vol2; it had no
citations and collided case-insensitively with @inproceedings{wu2016}
(the cited Quantized CNNs paper) under bibtex-tidy's normalization.
- vol1/training/training.qmd: drop the dead UtilizationGap LEGO cell
(gpu_real_tflops_*, cluster_*_tflops_*) and the dead
TrainingModels.{gpt3_gpu_years,gpt3_compute_cost}_str exports plus
their unused upstream values.
- vol2/distributed_training/distributed_training.qmd: anchor the
orphaned [^fn-parameter-server] footnote on the body-prose mention
of "parameter-server systems" rather than deleting the definition.
manual-bracket hook (book-check-refs) green at this tip.
3.8 KiB
Citation Reference Validation Workflow
Use this workflow when the task is to verify that @citekey citations in
Quarto source actually support the local claim where they appear.
Packet Builder
Generate one packet per chapter-sized audit unit:
python3 book/tools/scripts/build_citation_reference_packets.py \
--out-dir review/citation-reference-validation
The packet builder scans the bibliography-scoped source trees used by
check_bib_qmd_integrity.py, skips code fences, YAML, raw HTML, inline code,
Quarto cross-references, CSS at-rules, and other non-citation @ syntax, and
embeds the scoped BibTeX entry for every cited key.
By default, normal book packets are grouped by chapter directory, such as
book/quarto/contents/vol2/inference/, so one subagent can audit the chapter as
a coherent unit. Frontmatter pages, part openers, appendices, and glossary pages
are separate chapter-like packets. _shelved*.qmd files are skipped unless a
future audit intentionally opts into dormant material. For narrow rechecks, use
--granularity qmd to restore the old one-packet-per-QMD behavior.
Use --all-qmd only when the audit intentionally includes site, slide, kit, or
other unscoped Quarto files.
Generated outputs:
summary.json: machine-readable packet inventory.agent_manifest.md: launch list and task prompt for chapter subagents.packets/*.citation-packet.json: one packet per audit unit.
Agent Assignment
Assign exactly one packet to each audit agent. Each agent owns that chapter or chapter-like audit unit from start to finish. The agent should:
- Read the source context and the embedded BibTeX metadata.
- Decide what local claim the citation is attached to.
- Inspect the cited source when the metadata is not enough to judge support.
- Judge whether the source supports that local claim, not the entire paragraph or chapter.
- Return only actionable problems and a short coverage summary.
- Prefer
needs_humanover guessing when the source cannot be inspected.
Source inspection is part of the task. Use DOI/publisher pages, arXiv, OpenReview, official docs, project pages, standards documents, or other primary sources. Search-result snippets are not evidence. Read enough of the paper or source to support the judgment.
Use these statuses:
valid: the cited source supports the local claim well enough.unsupported: the source does not back the claim.overbroad: the source supports a narrower or adjacent claim, and the local wording materially overclaims it.misplaced: the citation belongs on a different claim or sentence.stale: the source is superseded for a time-sensitive claim.needs_human: the source could not be inspected or the fit is ambiguous.
Do not flag low-confidence disagreements. Do not require a paper to support unrelated nearby prose, and do not flag reasonable synthesis merely because the paper uses different wording. Flag only citation usages where the source/claim fit is actually wrong, too broad, stale, misplaced, or impossible to verify.
Recommended finding shape:
{
"key": "citekey",
"source_file": "book/quarto/contents/vol2/inference/inference.qmd",
"line": 123,
"status": "unsupported",
"claim": "short paraphrase of the local claim",
"reason": "why the source does or does not support it",
"suggested_fix": "replace citation | add source | narrow claim | move citation | remove citation",
"evidence": "brief source evidence and URL/identifier, or what needs human review"
}
Merge Results
After the chapter agents finish, merge their reports into:
review/citation-reference-validation/report.md
Group findings by source file, keep line numbers clickable in review tools, and
do not edit .qmd prose until the citation findings have been reviewed.