---
name: locate-code-by-layer
description: "Token-bounded, architecture-first code location through a private codebase-memory Gateway. Use whenever an Agent must understand or change implementation code: diagnose bugs, add features, refactor, review code, locate routes/controllers/services/models/views, find symbol definitions, or trace call paths and dependencies. It selects a layer and module before symbol lookup, returns compact metadata and file/line ranges instead of source, and replaces direct use of raw codebase-memory MCP tools. Do not use it for a pure documentation/configuration lookup when an exact literal and narrow path are already known."
---

# Locate Code By Layer

Use the `codebase-navigator` MCP as the only routine code-discovery interface. It privately calls codebase-memory, enforces layer-first navigation, and returns a compact location packet.

## Agent decision

Before reading implementation files, ask whether the task requires finding where behavior is defined or connected. If yes, invoke this skill and start with `locate_code`. Do not attempt a repository-wide search first.

Provide the whole problem in one request. Include the observed behavior, expected behavior, exact error text, known symbol, route, or path hint when available. More discriminating input produces a smaller result.

## Required workflow

1. Call `locate_code` once with the complete problem. Include an exact error, known symbol, or path hint when available.
2. Follow the returned status:
   - `located`: read only `recommended_reads`, beginning with the first range.
   - `ambiguous`: call `refine_location` with one returned layer or candidate. Do not restart a global search.
   - `architecture_uncertain`: follow `next_action`. If it is `refine_location`, reuse the returned `locator_id` with one exact symbol/path clue. Otherwise call `get_project_outline`, choose a layer, then call `locate_code` with that layer.
   - `insufficient_coverage`: use `refine_location` with one discriminating hint. If still unresolved, report the indexed scope gap.
   - `dependency_missing`: stop discovery, explain that Codebase is required, and ask whether the user wants it installed. Never install it without explicit approval.
   - `dependency_misconfigured`, `dependency_not_executable`, or `dependency_unhealthy`: stop discovery, report the exact dependency repair action, and ask before changing system configuration or permissions. Do not misdiagnose these states as a narrower-problem issue.
   - `not_indexed`: stop discovery, explain that the resolved project has no usable Codebase index, and ask whether the user wants it indexed with the official Codebase tooling.
   - `stale_index`: stop discovery and ask whether the user wants the project index refreshed.
3. After reading at most the recommended ranges, form a concrete hypothesis. Read one directly related symbol only if the first range is insufficient.
4. Modify code and run the narrowest relevant test only after the target is established.

Installation, dependency repair, first-time indexing, and index refresh are external mutations and require explicit user confirmation. The read-only Gateway only detects these states and returns a consent-aware `next_action`; it never installs Codebase, changes system configuration or permissions, or changes an index itself.

For a location-only question, the first direct definition, assignment, or registration matching the requested construct is terminal evidence. Stop immediately and report that file/range; do not inspect callers, callees, adjacent implementations, or alternative files unless the user asked for behavior analysis.

## Tool rules

- Treat `locate_code` as the default entry point.
- When a path or symbol is known, pass it as `fileHint` or `knownSymbol`; the Gateway uses one compact, source-free exact search before falling back to architecture routing.
- Use `get_project_outline` only when architecture is uncertain or the user explicitly asks for an architecture view.
- Refine a locator at most twice. If two refinements fail, ask for a symbol, error text, or path clue.
- Never request pagination or expand all matches.
- Never ask the Gateway for source; open the returned repository-relative line ranges using the local filesystem.
- Do not call raw `search_graph`, `trace_path`, `get_code_snippet`, `query_graph`, or `get_architecture` from the hidden downstream MCP.
- Do not automatically install Codebase, create an index, or refresh an index. Ask the user first, then use only the official Codebase installation and indexing workflow after approval.

## Narrow fallback

Use shell search only for an exact error string, configuration key, generated file, Markdown, shell script, or a path explicitly reported as uncovered. Limit it to the selected module. Never run repository-wide broad search or read whole source files as a substitute for the Gateway.

After the Gateway exhausts its refinements, the entire shell fallback budget is one exact-literal search inside the selected layer/module and at most two exact line-range reads. Do not issue a second `rg`, widen the path, scan directories, or read a whole source file. If that budget does not establish the target, report the unresolved index/scope gap. For a location-only task, stop after the first matching definition, assignment, or registration.

## Result contract

The Gateway returns a location packet, never source code. The Agent receives:

- `status` and `next_action`, telling the Agent whether to read, refine, inspect the outline, or refresh the index;
- dependency failures use `offer_install`, `repair_dependency_config`, `repair_dependency_permissions`, or `repair_dependency`;
- missing and stale indexes use `offer_index` or `offer_index_refresh`;
- `selected_layer` and bounded module scopes, explaining which architectural area was chosen;
- at most three ranked symbol candidates with stable candidate IDs and confidence evidence;
- `recommended_reads`, containing at most two repository-relative files and exact line ranges;
- at most five one-hop callers, callees, or dependencies needed to validate the target;
- `locator_id` for at most two bounded refinements;
- an index fingerprint and response-budget record for freshness and token auditing.

After receiving `located`, read only the first recommended range. The packet is a navigation decision, not an instruction to load every candidate.

For installation, architecture, policy limits, configuration, and status meanings, read [references/gateway-architecture.md](references/gateway-architecture.md).