Comment by mcbg1541

Coding agents (and I) write `file.py:123` into plans, design notes and reviews all the time. In my own side project the docs had collected about 19,500 of them. When I traced them through git history, roughly 3 in 4 of the ones I could trace pointed at the wrong line. A wrong line number still lands on some code, so nothing looks broken.

So I measured 16 public repos with 20k+ stars (method and numbers in the README): in hand-written docs, 67.6% of line citations are already wrong, and 73% of all of them were written in the last 90 days. It looks like a new kind of doc rot that came with AI-assisted development.

linecite does three things:

- `linecite audit` judges existing file:line citations without changing anything. git blame dates each doc line; linecite reads the code as it was on that date and follows that line to today's code: ok / stale / gone.

- A citation format that is still an ordinary markdown link, with a title naming the code (a symbol plus a quoted fragment): [orders.py:310](app/orders.py#L310 "create_order: row.lock()"). `sync` rewrites the number when code moves (pre-commit hook); `check` fails CI when the quoted code is gone. `adopt --write` converts existing citations.

- `linecite affected <rev>` lists the doc paragraphs whose cited code a change touched, and the GitHub Action posts that list as a PR comment. That is the part a correct number can't give you: the line still exists, but the sentence about it may no longer be true.

pip install linecite (Python 3.11+, git). MIT. Symbols resolve for Python and YAML; in other languages you cite by quoted fragment.

What I'd most like feedback on: is the link-title format too clever? And how do you keep docs pointing at the right code today?