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.