ADR-063: Relations a reader cannot weigh without prose must be explained in the body

Context

A relation in frontmatter says that two documents are related, never how. source: LIT-541 on a practice tells a reader which paper to blame and nothing about what the paper showed; corrects: LIT-045 says a paper was wrong without saying about what. Until luria 0.33 nothing checked that the prose ever said it, and measuring showed the gap was real but narrow: with every reference field opted in on a scratch copy, practices already cited 575 of their 590 sources in the body, while notes cited 40 of the 378 papers they are readings of.

luria 0.33 added the check (explain: on a reference), and 0.33.2 gave it two strengths. cited (also spelled true) asks that the body cite each code the field holds somewhere, and takes the citation as serving the relation. stated also asks for a ref:: statement of the relation beside each citation, which luria link --fix writes. At either strength a code the body never cites is unexplained-relations, which only a person can fix, by writing the sentence; a statement’s — reason also counts as an explanation.

Decision

explain: cited on thirteen fields, chosen by one test: would a reader need prose to weigh this relation?

• Evidence and origin. SOTA.source, SOTA.introduced_by, THEORY.source. A recommendation is only as good as what its paper showed, and the body is where that is said.
• The explanation link. THEORY.explains. Which part of the practice the account explains is the claim itself.
• Disputes. corrects on all three schemes and SOTA.contested_by. A correction that does not say what was wrong cannot be checked.
• Lineage. extends on practices, theories and papers: what the later work could not stand without.
• Comparisons. compared_against on practices and papers: somebody ran the comparison, and what it showed is the point of recording it.

The explanation must be prose a reader sees. An HTML comment explaining a relation does not count, and neither does a code in backticks, which is a mention rather than a citation. Nor does a reference entry: Kingma et al. (2014), LIT-001 — ARXIV-1412.6980. names the paper and says nothing about it. Since luria 0.33.3 the check finds such entries by their shape, not by the ## Source heading they usually sit under, and an entry followed by a sentence about the paper is prose and does count.

Alternatives considered

• explain: stated. Tried first, when it was the only strength. The fixer wrote 1346 statements into 554 files, each beside a citation whose sentence already said what the relation was: the statement restated the frontmatter in a comment no reader sees. It found nothing cited does not; the finding that mattered was the 81 relations the prose never mentioned, and that is the same at both strengths. The statements were removed.

• Every reference field. Two kinds stay out because their meaning is complete without prose here:

  • the converse back-references luria link --fix writes (extended_by, corrected_by, explained_by), whose other end carries the prose;
  • NOTE.paper, where the note is the reading (338 uncited).

  Version 1 also left out compared_against (280 uncited) and LIT.extends (84), as noise and as a follow-up. That was the wrong reading of the count: a large number of unexplained relations on a field the test admits is the finding, not a reason to look away from it.

• Clearing the backlog with sentences nobody read for. The danger in a count this size is the thinnest sentence that passes: a clause that names the paper and says nothing it showed. Every explanation is written from reading: the cited paper’s note, its close reading where the record has one, and the paper itself where neither says enough. A relation the reading does not support is reported, not explained into existence.

• Acknowledging the uncited ones with — reason statements instead of prose. That is legitimate where the relation needs no more than a clause. It was not the default here: a reason hidden in a comment is exactly the invisible explanation this decision exists to end.

• Status quo. Every relation stays unexplained until someone happens to write about it. That is how 81 of them accumulated.

Consequences

• The pin moved from luria 0.31.0 to 0.33.2 in the same contribution. (0.33.0 crashed on the DOI-labelled links in five notes; 0.33.1 fixed that, and 0.33.2 added the cited strength.)
• 23 relations were cited only as backticked mentions: sources in recent practices and theories, and a few explains. They became citations.

• The remaining 58 had no citation at all, and each got a sentence written from what the two documents say. None was found unsupported. Two are stated as partial fits in their own prose: THEORY-032 explains only the Muon branch of SOTA-165, and SOTA-137 inherits SOTA-169’s widening but not its constraint.

• From now on, a new practice or theory that names a source it never discusses fails nothing, but it is reported, and the report names the file.

• Version 2 surfaces 954 warnings on luria 0.33.3:

  • 590 cited only in a reference entry (SOTA.source 267, SOTA.introduced_by 253, THEORY.source 70);
  • 364 never cited (LIT.compared_against 247, LIT.extends 84, SOTA.compared_against 33).

  In 38 of the reference-entry ones, the prose names the paper’s first author but not its code, and adding the code is the whole fix.