agent-navigability

Audit for unsearchable names, missing entry points, untyped data crossing module boundaries, and duplicate files that could own the same behavior. Fix the highest-cost items first, typically renaming generic core types like Data or Item to specific names that grep cleanly.

Attempt a real task in the repo and record where you opened irrelevant files, guessed locations, or got unhelpful search results. Then check deviations from the repo's dominant pattern using the structural checklist covering entry points, naming, types, tests, and commands.

Generic names like Data, Manager, Handler, Item, or util fail because grepping them returns hundreds of unrelated hits, forcing the agent to read files instead of searching. Specific names like InvoiceLineItem return roughly the places that matter.

Prefer orientation assets like AGENTS.md or priming commands when the structural fix is expensive or the code is under active development. Restructure only when the problem is ambiguity, such as two files plausibly owning the same behavior, which documentation cannot fix.

Phase by reversibility: mechanical renames and file moves first, then introduce a boundary seam, then the split itself, then cleanup. State the concrete payoff, name what breaks such as open PRs, and define a minimum viable phase so a partial migration still delivers value.

It only audits legibility, not correctness, runtime behavior, or error handling. It also cannot eliminate per-session re-derivation of structure entirely; that requires orientation assets like AGENTS.md or priming commands rather than more refactoring.