Spec Citation

Note: every §clause number in this document (§101, §205, §300-306 …) is an illustrative number used to demonstrate the citation form. None of them is the real clause number of any real document.

Spec Citation Discipline

When to use this

Any project where one spec or design document is cited by something else — a test assertion noting "per §101," a code comment saying "see §205," a planning document writing "main spec §300-306," a memory file using "§410-415" as a coordinate. These citations are live: change the spec and a citation may point at the wrong place and fail silently. This skill covers how to edit a spec without breaking them.

General rules

Rule 1: A §clause number is a live reference, not decoration

Once a section or clause number is cited elsewhere, it is a stable public interface (like a function signature). Callers rely on it to locate "which part of the spec." Treat clause numbers as an API when you edit: do not renumber casually, and never let an existing clause number come to mean different content.

Rule 2: Semantic anchors beat line numbers

Line numbers drift (insert one line above and everything below is off by one); semantic anchors (section titles, §clause numbers, distinctive phrases) are stable.

• When citing: write "§101, the attainment-rate family" rather than "line 101."
• When locating: grep for §101 or for the heading text; do not trust a line number you remember.
• This is also why editing tools should locate by unique text anchors rather than by line number.

Rule 3: Before editing a spec, check whether any live workstream cites that section

A "live workstream" is work in progress or about to resume — it has a branch, a plan, or a memory coordinate pointing at it. Before editing any part of the spec, search the whole repo for tests, code, plans, or memory files that cite it:

grep -rn "§101\|attainment-rate family" .        # search the clause number AND the semantic anchor

A hit means that section is an occupied interface: changing it requires changing every citing party in the same move (exactly like changing a function signature means changing every caller).

Rule 4: Never insert lines before a cited section (numbering stability)

When adding spec content, where you insert determines what happens to existing clause numbers:

• Appending after the cited section, or at the end of the file → existing numbers do not move and no citation breaks. Safe; make this the default.
• Inserting before a cited section (especially anything that pushes later numbering along) → every clause number after it shifts and the citations point wrong en masse. Forbidden, unless you update every citing party in the same change.
• Give new material a new clause number (continue from the highest); do not wedge it between old ones.
• No renumbering (hard line): an anchor's entire value is that it never changes, and renumbering destroys exactly that value. If you believe renumbering is unavoidable, stop, and hand it to the owner as a standalone engineering proposal instead of migrating it yourself — one person quietly renumbering and fixing up a few citations along the way will almost certainly miss one, and that one fails silently.

Rule 5: A spec you do not own is read-only

Specs are often maintained by an owner (a person editing in their own working tree, by hand). If the spec file is marked as maintained by someone → cite it, never edit it on their behalf; put your additions in a separate design or plan document that cites it, and leave the main file alone. Confirm authorization before touching the main file.

Case files from this project (supporting evidence, not required for the general rules)

• The coordinate system: one financial-reporting automation project uses §<approximate line number> as a coordinate in its main spec (§101 / §205 / §300-306 …), cited from four places: test ground-truth annotations (clause-number field="§101"), code comments, plan/spec documents, and memory files. Every ground-truth entry in the conflict fixture set carries its spec clause number so it is "traceable, not the annotator's opinion" — which is Rule 1's "a clause number is a public interface" in practice.
• The main file is owner-maintained (Rule 5): the main spec is maintained by hand, by its owner, in their working tree. When the third batch of work started, the main spec file turned out to have been modified in that working tree by the owner → do not touch it, do not commit it; cite its §300-306 and so on from separate spec/plan documents only. That is "read-only when you do not own it" in practice.
• Semantic anchors saving the day (Rule 2): nominally the clause numbers are "approximately the line number," but locating is always done by grepping the §clause number or the heading text, never from a remembered line number — because the owner is inserting material continuously, the line numbers drifted long ago, and only the clause-as-semantic-label stays stable.