agent's citation links point to page numbers from the draft, not the executed version - every citation off by two

TL;DR: Regenerate every citation against the executed version, and keep a per-version page map so citations always name the version they were computed from. The agent extracted page numbers from the draft, the executed version re-paginated, and every link inherited the draft's numbering.

agent's citation links point to page numbers from the draft, not the executed version  -  every citation off by two

1. Confirm the version skew. Open the executed version at one cited page and compare with what the citation claims is there. Expected: the cited clause is consistently N pages away (here, two), confirming a pagination shift between versions rather than random error.

1. Build a page map between the versions. Align the draft and executed texts on section headings, then record how page numbers translate (draft page P maps to executed page Q). Expected: a mapping table covering every cited page, or a constant offset if the shift is uniform.

1. Rewrite the citations against the executed version. For each citation, look up the cited clause by section number or quoted text in the executed version and record its actual page there. Expected: every citation now opens the executed version on the page that really contains the clause.

1. Change the pipeline to cite section numbers as the primary locator, with page numbers as a convenience. Sections survive re-pagination; pages do not. Expected: future citations stay valid even when the next version re-paginates again.

1. Stamp every citation with the version it was computed from (document name plus version or execution date). Expected: a reader can tell at a glance whether a citation belongs to the draft or the executed copy, and stale citations are identifiable.

Use this when

• citations open the right document on the wrong page
• every citation is off by the same fixed number of pages
• citations were generated from a draft but consumed against the executed version
• re-pagination between versions broke a previously correct citation set

Not for this skill when

• citations point at the wrong clause entirely, not just the wrong page (check the extraction or clause linker)
• the cited text does not exist in the executed version at all (the clause may have been deleted; that is a substantive finding, not a pagination bug)
• page numbers are right but the links themselves are broken (check the link format or viewer)

Variant phrasings

• citation page numbers came from the draft, executed version paginated differently
• agent cited draft page numbers and every link is off by two
• redline citations point at the wrong pages in the final agreement
• page references shifted between draft and executed contract

Why it happens

Page numbers are a property of a specific rendering of a specific version, not of the clause. Any edit that adds or removes content before a clause (a new recital, a lengthened definition) shifts every page after it. Pipelines that store bare page numbers are storing coordinates in a map that gets redrawn every version.

Edge cases

• A constant offset is the easy case. Insertions mid-document make the offset piecewise; the section-heading alignment in step 2 handles that.
• If the executed version is scanned while the draft was digital, page counts can differ for rendering reasons too. Align on text, not on page count.
• Some viewers number pages from the PDF page index (starting at the cover) while others use printed folio numbers. Pick one convention and record it with the citation.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_JwIrqqbrHEmCwNeveLKRNA