Repo Wayfinder

Repo Wayfinder

Treat documentation as a wayfinder, not proof. Design a documentation system for a new project or repair one for an existing project by giving each document one owning question, an update trigger, and routes to the sources that own its claims. Current behavior usually belongs to code, types, schemas, configuration, or another executable contract. Tests and driven probes verify that owner; they do not become a second owner.

Default to a read-only diagnosis. Enter the apply branch only when the user explicitly asks to change files.

1. Pin identity and observation

Read every applicable instruction file before judging the repository. Record:

• repository root, branch, exact commit, and dirty paths;
• the user-selected scope;
• package or service boundaries;
• the instruction chain that applies to each scoped directory.

Before designing the on-ramp or topology, state the project's identity contract:

• purpose and intended users;
• central model or structural bet, when one exists;
• explicit non-goals and replacement-versus-support boundaries;
• what exists now versus what is only intended.

For an existing project, derive candidates from the user request, entry documents, code, and live journeys. For a new project, use the accepted goal, plan, design, and code skeleton as provisional authority. If the user, documentation, and implementation imply materially different identities, stop the topology decision and ask which one is declared. Do not let the current README silently decide intent.

Preserve unrelated work. Treat an uncommitted tree as observable state, not as a reason to clean it.

Complete when: the work names the exact state and scope it describes, and one identity contract is accepted or the unresolved conflict is explicit.

2. Inventory authority

For an existing project, use fast repository-native discovery such as rg --files and git ls-files. Include root and nested instruction files, READMEs, docs/, runbooks, protocol documents, decisions, proposals, measurements, generated references, and issue templates in scope. For a new project, inventory the available goal, plan, design, configuration, code skeleton, commands, and package or service boundaries; record missing owning questions instead of inventing answers.

Assign every discovered document a primary role:

• on-ramp — what this is, where to start;
• routing or agent instruction;
• map — where components live and how they connect;
• current contract;
• operational runbook;
• measurement or evidence;
• rationale or decision;
• proposal or plan;
• generated reference;
• unclassified.

Tag lifecycle — current, proposed, historical — separately from role.

Record two roles, not one: the observed role the content performs, and the declared role it is intended to carry. A filename decides neither, and existing content is not evidence of intent — ARCHITECTURE.md is a map in one repository and a rationale in the next. A mismatch is itself a primary finding. Where the declared role is unstated and two readings would produce materially different documents, ask.

For each document, identify its owning question, audience, update trigger, proof boundary, and any current claims it duplicates. Classify sections or claims separately when one file mixes roles or time domains; do not force a heterogeneous file into one authority class. A document with no owning question is a sediment candidate.

Maintain a document rules table throughout the run:

For a new project, rows are proposed rather than observed. Omit a row when no distinct owning question justifies the document.

Complete when: every existing document in scope has an observed role, a declared role, and a lifecycle tag or is explicitly unclassified; every mismatch and mixed block is recorded; and every proposed document has a complete rules-table row.

3. Walk real journeys

Select two to four representative tasks from the user's request, current issue surface, or actual or planned package entry points. Trace each journey:

task -> first route -> next pointer -> owning source -> test or probe

For a new project, a journey may end at an accepted goal, design, plan, or proposed code owner. Mark that route proposed and name the future acceptance evidence; do not describe planned behavior in the present tense.

Inspect the owning code before accepting a document's present-tense verb, field, command, lifecycle, or boundary. Use types, schemas, configuration, manifests, and public exports as applicable executable owners. Use tests and direct probes as conformance evidence. When they disagree, report the conflict; a green test does not override its implementation, and failing conformance does not reveal the intended repair by itself. Mark inaccessible or unresolved claims needs evidence; do not fill the gap from convention or memory.

Keep unlike time domains separate:

• code-backed contracts answer what callers may rely on now;
• runbooks answer how to operate now;
• issues answer what work is currently proposed;
• decisions, bets, and measurements preserve what was believed or observed.

Complete when: every journey ends at an owner and a verification path, or at a named unknown.

4. Adjudicate the map

Give each authority-bearing unit one disposition: use the whole document when it is homogeneous, and a section or claim when it is mixed. Use dispositions for existing material; use a proposed rules-table row for a new document.

• Keep — it owns a distinct question and has a credible update trigger.
• Point — replace copied facts with a route to their owner.
• Co-locate — move a genuinely local rule beside the code it governs.
• Mark historical — preserve it while removing present-tense authority.
• Delete — it has no unique evidence, history, or owning question.
• Needs evidence — its authority cannot yet be judged.

Apply these topology rules:

• Guidance is evergreen: a document carries facts whose change trigger matches its owning question. Not "never changes" — a map updates when a directory's purpose changes, which is its trigger; but finishing a planned phase must not drag the on-ramp and the instruction file with it. Route live state to its owner: counts and benchmarks to evidence, what-exists-yet to the plan, behavior to the code. Judge by trigger, not by whether a number appears — a version inside a versioned contract or a runbook is where it belongs.
• Give each current claim one authoritative owner; allow many pointers.
• Keep root AGENTS.md to repo-wide, non-inferable constraints, verification, and task routing. Add nested instructions only where local rules materially differ.
• Keep README as the public or package on-ramp, not an architecture and policy landfill.
• Keep an architecture document only when a cross-boundary mental model cannot be recovered cheaply from the owning sources.
• Let runbooks own operations. Let executable sources own behavior and use tests or probes to verify conformance.
• Keep necessary explanation that gives a human or agent a mental model, minimal usage example, or deliberate boundary. Treat precise version numbers, exhaustive implementation lists, internal lifecycle detail, and error strings as mirrors unless the repository explicitly declares them as a code-backed public contract.
• Preserve evidence and historical ledgers under their recorded lifecycle; age alone is not staleness.
• Keep a deliberately deferred choice in rationale or decisions. Put an accepted defect with an ordered repair and exit proof in the plan; the decision document may point to it but must not own the repair twice.
• Add a durable roadmap only when short-lived delivery plans are intentionally archived and no current owner answers which product or system capability horizon remains eligible for later work. Let that roadmap own capability ordering, promotion evidence, and the remainder after a plan closes—not implementation tasks or execution authority. Keep commissioned work in the active goal or issue, require plan completion or abandonment to reconcile the roadmap, and omit the roadmap when an existing current plan already owns this question.
• Create no document merely to complete a taxonomy. Require every proposed file to state its owning question, non-ownership boundary, update trigger, and proof boundary.
• Automate syntax, generated coupling, and link integrity where useful. Leave semantic authority to code-grounded review.

Before proposing, creating, splitting, or materially rewriting a document, read references/archetypes.md and references/document-templates.md. Treat the templates as section menus: admit a section only when the repository justifies its reader, question, and resulting action. Before proposing a new topology or AGENTS.md layer, also read references/topology.md. Re-derive every shape from the target repository; never paste a template blind.

Complete when: every authority-bearing unit and duplicate has exactly one disposition, and every proposed file survives the owning-question test.

5. Return a decision surface

Lead with the decision rather than an evidence dump. Apply the same attention test to the response as to the documents: keep the main surface to lines that change a decision, action, or route; move challenge material to the appendix. Return:

1. Verdict — what is actually broken and the smallest useful correction.
2. Identity contract — purpose, users, central model, non-goals, and current versus intended boundary.
3. Document rules table — path, role, ownership and non-ownership, trigger, proof, and lifecycle for the proposed system.
4. Wayfinder — a compact task -> start -> authority -> verification table.
5. Disposition and minimal change set — for an existing project, current path plus section or claim, disposition, and why; then ordered edits, with deletions and pointers before additions. Name every created, split, or rewritten document's archetype and destination path here, where the user can accept or reject them.
6. Verification appendix — exact commit, source anchors, probes, and residual unknowns for someone who wants to challenge the verdict.

Make the main decision legible without reading source. Put its retraceable source trail in the verification appendix for refutation, not self-certification.

Complete when: the user can accept the project identity, document rules, file set, and edits without reading the appendix, while a verifier can retrace the evidence.

6. Apply only on explicit request

Revalidate the premise at the current HEAD, then edit the fewest files that realize the accepted dispositions. Preserve user changes and repository-specific lifecycles. Run the relevant link, build, test, and driven-flow checks. Follow any repository-required independent review; if a fresh context or refuter is unavailable, mark independent verification as outstanding rather than silently self-certifying.

Writing one document and then the next carries rules forward into both, and a correction that lands in one copy leaves the pair issuing opposite instructions — which a reader resolves by obeying whichever comes first. So finish with four sweeps across the whole set:

• owner — for each mutable claim, name its owner, then classify every other occurrence as pointer, evidence citation, or a second assertion. Grep only generates candidates: a pointer is a legitimate second hit, and a rephrased restatement is not greppable at all.
• evergreen — in guidance documents, find facts whose change trigger does not match the owning question, and route them to the owner whose trigger does.
• reference — after any renumber or rename, resolve every identifier: phase and section labels, numbered principles, paths, heading anchors, renamed symbols, routing destinations. Search identifiers, not old headings — a renamed heading puts its own references out of reach of a heading search.
• cold-start — have a fresh context or refuter re-walk two journeys from the entry document. A same-context author may run a navigation smoke test, but cannot call it an independent cold start. Step 3 walked the journeys before the edits; they prove navigation only if they still land after.

Do not commit, push, open issues, or publish unless the user asks.

Complete when: each changed path implements an accepted disposition, all four sweeps are clean, every affected journey still reaches its owner, and every surviving line changes an action, a judgment, or a route, or supports independent verification.