Skip to content

todo: nothing checks that a spec cross-reference supports its claim #226

Description

@thxCode

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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    todoWork a pull request knowingly left undone

    Type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions