Workflow · last verified 2026-08-17

Auditing an inherited citation before you correct it

The job this workflow does

Most citation and configuration formats have a shorthand for "same as the thing above": a bare Same in a source column, an id. in a legal footnote, an unset CSS property that falls back to the parent, a YAML value left out of an override block so the base file's value shows through. The shorthand exists for a good reason — restating an identical value on every row is noise, and noise is where real changes go unnoticed. But the shorthand buys that compression by turning a value into a pointer, and a pointer has a property a value doesn't: it can be right for the row that wrote it and wrong for a row that only inherited it, at the same time, after a single correction to something upstream.

The failure is specific and easy to reproduce: someone finds a genuinely wrong fact, traces it to its source, and fixes the source. The fix is correct. Every row that read that source directly is now correct. And every row that read it only by inheriting from the row above — including a row whose facts were never wrong, and a row whose author never touched it — has just changed meaning, because the pointer it holds resolves somewhere new. Nobody edited that row. A diff of the file shows one line changed. The blast radius is every row beneath it that used the shorthand, and the diff cannot show you that, because inheritance is resolved by a reader, not stored in the file.

The workflow

1. Find every place inheritance is legal, before you touch anything

Grep for the shorthand token itself, not for the fact you are about to correct. If the convention is a bare Same, ibid, id., an empty cell, or a key simply absent from an override block, that token is the thing to enumerate first — a full list of every row currently relying on inheritance, independent of which one prompted the fix. This list is the set of rows you are responsible for before you write a single correction, not after.

2. Trace forward from the row you're correcting, not just backward from the row you noticed

The instinct that finds the bug is backward-tracing: a fact looks wrong, you follow its citation upstream to the source, and you fix the source. That instinct stops exactly where the fix is applied. It does not ask the second question, which is symmetric and just as necessary: what points at the row I am about to change? Walk forward from the corrected row through every inheriting row on the list from step 1, and for each one, re-derive what it now resolves to and check that it still means what its author intended.

3. Make every reference explicit — kill the shorthand where it was doing real work

Once the sweep is done, the fix is not "correct the one row and move on" — it is to stop using inheritance for anything an independent reader needs to audit. Write out the resolved value on every row the shorthand used to cover. This costs the repetition the shorthand was invented to avoid, and it is the right trade for anything an audit has to check one row at a time: a chain is auditable at the chain's root or not at all, and a table of explicit values is auditable row by row, which is the property you actually wanted.

4. Mark the row that must never re-point, and say why

Some rows are structurally different from the rest — not "currently correct" but "correct for a reason the next sweep can't see," typically because the row rests on a source the others don't, or a constraint the others don't carry. That row needs a marker that survives the next correction, not just today's fix: a comment or a flag that says, explicitly, do not repoint this from above, and why. A future sweep that only checks "does this cite something reasonable" will pass a wrongly re-pointed row every time, because the new target is usually reasonable — just not the one this specific row required.

5. Re-run the enumeration from step 1 as the verification

The check that proves the fix is the same grep that started it: if the shorthand token still appears anywhere in scope, the sweep isn't finished. Zero remaining instances of the inheritance token is the pass condition — not "the row I was asked about now looks right," which is the check that missed the second-order defect in the first place.

As built in this repo

docs/CURRICULUM.md keeps a provenance ledger — a table mapping curriculum facts to their sources — and its source column used to permit a bare marker meaning "inherit the row above." A correction on 2026-08-14 re-pointed one row off a source that should never have been cited publicly and onto a citable one. The fix was correct on its own terms. Every row beneath it that had inherited from that row silently re-aimed at the new target too, including the one row in the table whose underlying facts genuinely could not be sourced to anything public — a row nobody had edited, and whose citation was now wrong in the opposite direction from the row that had just been fixed.

The repair followed the four steps above: every inheriting row was enumerated, traced forward, and rewritten with its own explicit citation; the one row that cannot be repointed now carries a marker saying so directly in the table, so the next correction sees a rule instead of having to rediscover the constraint. What is deliberately not on this page is the ledger's contents — the specific facts, the specific source names beyond "a private partner guide" for the one row that rests on one, or any of the exam material the private guide covers. None of that is the lesson. The lesson is the shape of the failure: a corrected pointer rewrites everything that points at it, and a chain that permits "same as above" cannot be audited one row at a time, no matter how careful the row-by-row review is.

Pitfalls

• Reviewing only the row that was reported. A code review or content review naturally scopes to the diff, and the diff is one line. The defect is never in the diff — it's in every row the diff doesn't mention.
• Treating "looks plausible" as the verification. A re-pointed row usually resolves to something reasonable, because the new target is a real, correct fact — just not the fact that specific row needed. A spot check that only asks "is this citation sane" will pass a wrongly re-pointed row every time.
• Marking the exception after the next sweep, not before. A do-not-repoint marker written in response to this incident protects against the next one. Written in response to the next incident, it protects against nothing — it has to exist before the sweep that would otherwise catch it.
• Assuming the shorthand is rare enough to check by eye. The convention exists because restating a value on every row is noise; that's exactly why a table using it usually has more inheriting rows than the reviewer expects, and an eyeball scan under-counts them the same way a diff does.

When not to use this workflow

Skip it if the format doesn't have an inheritance shorthand at all — a table where every row restates its own citation in full has no chain to trace, only individually wrong or right rows, and the ordinary correct-the-row-and-check-it review is sufficient. It's also unnecessary for shorthand that's genuinely local and non-transitive — a citation that means "see the previous sentence" and nothing reads it from three sentences away doesn't have the multi-hop blast radius this workflow exists for. The tell is whether a single correction can, structurally, change something the editor never opened: if yes, sweep before you commit the fix; if a change to any one row is provably confined to that row, this workflow has nothing to add.

How you know it is working

• Occurrences of the inheritance token, post-sweep — should be zero in the corrected table, or explicitly limited to a documented set. A remaining instance is unfinished work, not an edge case.
• Do-not-repoint markers present on every structurally exceptional row — checked as part of the same pass, not left to be rediscovered by the next person who trips over the exception.
• Whether the review that found the original defect could have found the second one. If the answer is no — if it only checked the row it was told about — the review method, not just the table, needs the fix.

Changelog

• 2026-08-17 — initial version, written from a 2026-08-14 incident in this platform's own curriculum provenance ledger.