The gap
Specs in this repository carry internal cross-references — "see F6", "measured below", "per T12b",
"the table in section 4". Nothing checks any of them. Not at authoring time, not in make lint docs,
not in CI.
An instance is on main today and has its own report; that one is about the specific sentence. This
issue is about the class, and it stays open after that sentence is corrected.
Two halves, and only one of them is mechanically checkable
Half one — does the label exist? "see F6" where no F6 heading exists in the file. This is a
grep, and a check for it is cheap.
Half two — does the target support the claim? "see F6" where F6 exists but is about something
else. This is not mechanically checkable, and it is the half that actually bit: the instance found
had a real F6, in the same document, on an adjacent topic, using the same vocabulary as the claim
citing it.
⇒ ⚠️ Implementing only half one produces a check that passes on the failure we already have.
A green run would then read as "cross-references verified", which is worse than no check: it converts
an unexamined area into an area someone believes was examined.
Why the second half is not hopeless
It cannot be fully automated, but it can be made visible:
- A cross-reference is a claim of the form "section X establishes Y". Requiring the citing sentence
to state what it expects to find there — rather than only where — makes the mismatch legible to
a reader without them having to reconstruct the intent.
- The instance found had a second tell that is mechanical: the claim carried a number
("two of the five") and the cited section contains no such number. A check for
"citing sentence has a figure, cited section has none" would have flagged it. It would also produce
false positives, which is why it is a reviewer prompt rather than a gate.
What does not count as filling this gap
- A checker for half one alone, shipped as "cross-reference validation". See the warning above: it is
green on the known failure.
- Fixing the instance already reported. That one is a sentence; this is the absence of anything that
would have caught it, and it stays open after that sentence is right.
- A convention documented in the docs skill saying "check your cross-references". The convention for
spec Status: values was already written down and was violated four times in two days; a written
rule with nothing observing it is the shape this issue records, not a remedy for it.
- Restricting the check to specs. The same construct appears in
docs/ and in code comments, and the
instance found was in a spec only because that is where someone happened to look.
The gap
Specs in this repository carry internal cross-references — "see F6", "measured below", "per T12b",
"the table in section 4". Nothing checks any of them. Not at authoring time, not in
make lint docs,not in CI.
An instance is on
maintoday and has its own report; that one is about the specific sentence. Thisissue is about the class, and it stays open after that sentence is corrected.
Two halves, and only one of them is mechanically checkable
Half one — does the label exist? "see F6" where no
F6heading exists in the file. This is agrep, and a check for it is cheap.
Half two — does the target support the claim? "see F6" where
F6exists but is about somethingelse. This is not mechanically checkable, and it is the half that actually bit: the instance found
had a real
F6, in the same document, on an adjacent topic, using the same vocabulary as the claimciting it.
⇒⚠️ Implementing only half one produces a check that passes on the failure we already have.
A green run would then read as "cross-references verified", which is worse than no check: it converts
an unexamined area into an area someone believes was examined.
Why the second half is not hopeless
It cannot be fully automated, but it can be made visible:
to state what it expects to find there — rather than only where — makes the mismatch legible to
a reader without them having to reconstruct the intent.
("two of the five") and the cited section contains no such number. A check for
"citing sentence has a figure, cited section has none" would have flagged it. It would also produce
false positives, which is why it is a reviewer prompt rather than a gate.
What does not count as filling this gap
green on the known failure.
would have caught it, and it stays open after that sentence is right.
spec
Status:values was already written down and was violated four times in two days; a writtenrule with nothing observing it is the shape this issue records, not a remedy for it.
docs/and in code comments, and theinstance found was in a spec only because that is where someone happened to look.