evidence-anchors

Evidence Anchors — grounding claims about existing code

You are writing a document that asserts things about the codebase. Reviewers — human or agent — will check whether your plan is good, but almost nobody re-checks whether your premises are true. A false premise that supports a correct-looking conclusion sails through every review. This skill closes that hole: every load-bearing claim carries a citation that forces you to open the file, and a deterministic checker re-verifies the citation afterward.

The convention attaches to anything a human approves, not just formal design docs. That includes a plan written in plan mode — ephemeral is fine; the anchor gates the approval moment, not the archive — and a PR description, which is the one claim-carrying document every workflow has. When a plan or PR body asserts something load-bearing about existing code, anchor it.

Full spec: https://github.com/armanfatemi/nullius/blob/main/spec/evidence-anchors.md

What needs an anchor

A load-bearing claim is a statement about what the existing code, config, or infrastructure does, on which a design decision rests — anything in a rationale, an "alternatives considered … rejected because …", a risk assessment, or a constraint.

• "The deployment runs 2 replicas" → load-bearing, cite it.
• "PaymentProcessor already owns a retry queue" → load-bearing, cite it.
• "No service reads this collection" → load-bearing absence, cite the search.
• "Option B is simpler to reason about" → judgment, NO anchor.
• "Users may find this confusing" → product risk, NO anchor.

The rule: if you cannot cite it, you may not assert it. Move the claim to an ## Open questions section instead. Do not decorate judgment calls with citations — citation theater trains readers to skim past the anchors.

The presence form — the thing exists

Open the file. Then write:

**Evidence:** `path/to/file.ext:LINE` — `exact text appearing on that line`

• Path is repo-relative (never absolute, never ~, never ..).
• The quoted text must actually appear on that line (whitespace is normalized, so indentation differences are fine).
• If the cited text itself contains a backtick, use a double-backtick span: **Evidence:** `libs/x.ts:4` —const q = query {};
• Quote something that could be wrong. Matching is substring-based, so a one- or two-character quote is trivially true and asserts nothing; it verifies as WEAK-ANCHOR. Quote enough of the line that a real change to the code would contradict it.
• Quote something that occurs once. A quote matching several lines is WEAK-ANCHOR while it sits on its cited line, and a hard UNPINNED failure once that line number goes stale — at that point neither half of the citation identifies anything. A stale line number on its own is not a failure: DRIFT and WRONG-LINE pass, and tell you the citation needs updating.
• Stamp the commit you read. Run git rev-parse --short HEAD and put it in the anchor: