agent-navigabilitylisted

# Agent navigability audit Every fresh agent session re-derives where things live. That cost is paid on every run, forever, and it scales with how many agents you run rather than how many engineers you have. A structure that's merely tolerable for a team that already knows it can be genuinely expensive for something that doesn't. The test throughout: **can an agent find the right file without reading the wrong ones?** Not "is this well designed" — a clean architecture can still be unnavigable, and a messy one can be easy to search. Legibility is a separate axis from quality, and this skill only audits legibility. Findings here are structural. If the question is about runtime output, error handling, or observability, use `logging-audit` instead — that's the behavioural half of the same problem. --- ## Step 1: Navigate it yourself first Don't read the repo and form opinions. **Attempt a real task and watch where you struggle.** Pick something plausible — "add a field to the main entity and thread it through", "find every place that writes to storage", "add an endpoint like the existing ones" — and note, concretely: - Which files you opened that turned out to be irrelevant - Where you had to guess, and what you guessed from - Searches that returned too much to be useful - Points where you couldn't tell which of several similar files was the live one That list *is* the finding set. Structural advice derived from reading a tree is generic and mostly unactionable; advice de