repo-wayfinder

Repo Wayfinder

Documentation routes; it does not prove. Every current claim has one owner — code, a type, a schema, configuration, or one living document — and every other mention is a pointer to it. Tests and probes verify the owner without becoming a second one.

A cache is a sentence that restates the code, so a refactor that keeps the design would make it false: a constant, a field name, a page size, which file does what, the order of queries. It is a second owner, edited with every change or left stale. A living document states what the code cannot: the job and the boundary, the invariant a caller relies on, the hazard that bit, the reason. When a document drifts again after each fact check, cut its cache instead of checking it again.

A sentence is stale when its owner now says otherwise: a present-tense claim the code contradicts, a decision a later one superseded, a link to a moved or removed target, a status or next step shown as current that is done or dropped. The aim is no stale sentence, not a length: cache goes because it goes stale, and a long document of owned, true sentences stays.

• A living document is edited in place to stay current. It owns one question and changes when that question's answer changes: its update trigger.
• A record is dated and written once (a review, report, meeting note), kept in a folder with an index, and corrected by an attached dated note, never rewritten.

Quick pass (default)

1. Pin the commit agents actually load (the primary checkout's branch: a rule changed on an unmerged branch still loads from the trunk), the scope and the instruction chain (AGENTS.md, AGENTS.override.md, CLAUDE.md, GEMINI.md, tool rule folders, an agent memory index, ignored local files), and measure the chain against the loading limits.
2. Walk two to four real tasks from a cold start: task -> first route -> next pointer -> owner -> test or probe. Check every present-tense claim and stated decision on the way against its owner; each stale one is a finding (when a test and its implementation disagree, report it). Count the files and words each walk read. Where agent session transcripts exist, also count which documents agents actually opened in recent sessions: a historical file opened at all is a finding.
3. For each code-adjacent document the walks read, measure over the last month or two the share of its code's changes that also edit it, and the changes that only re-sync it; count from the module's first build, per merged change. A document that changes with most of them, or whose stated update trigger is "the implementation changes", is a cache: report that, with sample cache sentences, rather than its stale facts.
4. In the instruction chain and the documents the walks read, find current claims stated in more than one place (versions, commands, behaviours, limits) and name each one's owner. Also flag sections with no owning question, and rules written for a weaker model (read X before every edit, always run every test, a boundary stated more strongly than its risk).
5. Report the findings, each with evidence and one disposition, and the choices only the user can make.