codebase-search · diff
v2.0 to v2.1
130 added, 181 removed. Audit A to A.
---
name: codebase-search
description: >
- Search and navigate codebases with an evidence-first workflow. Use when the user
- needs repo navigation, call-site tracing, code archaeology, ownership discovery,
- impact analysis, entry-point mapping, config hunting, or pre-change discovery —
- even if they do not explicitly say "search". Choose between exact-text search,
- symbol/indexed search, structural search, and file discovery, then hand off cleanly
- to debugging, refactoring, review, or graph-based architecture analysis.
+ Route repo-navigation requests to the right search packet before editing anything.
+ Use when the user needs to find where something lives, who references it, which
+ files own a config/content surface, what must be inspected before a change, or
+ how to narrow a large repo without drifting into debugging or refactoring.
+ Choose one packet: exact-text, symbol/indexed, structural, config/content,
+ hosted search, or graph/path trace. Triggers on: where is this defined, who uses
+ this, find call sites, config ownership, entry point, impact before refactor,
+ shortcode/frontmatter search, scene/asset reference hunt, repo archaeology.
allowed-tools: Read Grep Glob Bash
metadata:
tags: codebase-search, code-navigation, repo-triage, impact-analysis, grep, ripgrep, ast-grep
platforms: Claude, ChatGPT, Gemini, Codex
- version: "2.0"
+ version: "2.1"
---
# Codebase Search
## When to use this skill
- - The user needs to **find where something lives** before changing it.
- - The user asks for **call sites, ownership, entry points, imports, configs, or impact analysis**.
- - The task is mostly **repo navigation / evidence gathering**, not diagnosis or refactoring yet.
- - The codebase is large enough that random file reading will waste time.
- - The user wants to know **what to inspect next** before implementation, review, or bug fixing.
+ - The main job is **repo navigation before edits**.
+ - The user needs to find **definitions, call sites, entry points, config owners, tests, templates, content references, or likely impact surface**.
+ - The repo is large enough that random file reading will waste time.
+ - The request is really **"where does this live / what uses it / what should I inspect first?"** even if the user never says "search".
+ - The repo may be **app code, infra/config, content/templates, or game tooling/assets**, and the first step is still discovery.
Do **not** use this skill as the main workflow when:
- - The user already knows the file and needs root-cause diagnosis → use `debugging` or `log-analysis`.
- - The user is changing structure while preserving behavior → use `code-refactoring`.
- - The user wants persistent graph-backed architecture mapping across a whole corpus → use `graphify`.
- - The user wants judgment on a diff or PR → use `code-review`.
+ - The user already found the area and now needs root-cause diagnosis → use `debugging` or `log-analysis`.
+ - The user wants a behavior-preserving cleanup or migration plan → use `code-refactoring`.
+ - The user wants judgment on a concrete diff / PR → use `code-review`.
+ - The user wants a persistent whole-repo or mixed-corpus structure map → use `graphify`.
## Core idea
- Codebase search is a staged narrowing workflow:
- 1. classify the search goal
- 2. choose the cheapest search lane that can answer it
- 3. narrow scope by path / language / owner / symbol
- 4. read the winning files
- 5. return a compact evidence map with next route-outs
-
- Do **not** dump random search output. The goal is decision-quality navigation.
-
- ## Instructions
-
- ### Step 1: Classify the request
- First identify which search job this really is:
-
- | Search job | Typical user phrasing | Best starting lane |
- |---|---|---|
- | Known text lookup | "Find this env var", "where is this error string used?" | exact-text search |
- | Symbol / API tracing | "Where is this function called?" | symbol/indexed search or exact-text fallback |
- | Structural pattern hunt | "Find all async handlers missing auth", "match this AST shape" | structural search |
- | File / ownership discovery | "Where does config live?", "what files implement checkout?" | file discovery + exact-text search |
- | Architecture / impact map | "What do I need to inspect before changing X?" | staged search + evidence map |
+ `codebase-search` should act like a **packet router**, not a giant search tutorial.
- If the task mixes multiple jobs, start with the narrowest lane that reduces uncertainty fastest.
+ 1. Normalize the request into **one primary packet**.
+ 2. Narrow scope before dumping matches.
+ 3. Read only the winning files.
+ 4. Return a compact evidence map.
+ 5. Route out as soon as search is no longer the bottleneck.
- ### Step 2: Choose the search lane
+ Read these support docs before choosing the packet:
+ - [references/intake-packets-and-route-outs.md](references/intake-packets-and-route-outs.md)
+ - [references/search-modes.md](references/search-modes.md)
+ - [references/evidence-map-template.md](references/evidence-map-template.md)
+ - [references/handoff-boundaries.md](references/handoff-boundaries.md)
- #### Lane A — Exact-text search
- Use for known names, strings, flags, log lines, SQL fragments, and import paths.
+ ## Instructions
- Good fits:
- - function/class names you already know
- - environment variables
- - error messages
- - config keys
- - literal API routes
+ ### Step 1: Normalize the request
+ Convert the prompt into this intake shape first:
- Default pattern:
- ```bash
- rg -n --hidden --glob '!node_modules' --glob '!dist' 'search_term' .
+ ```yaml
+ codebase_search_packet:
+ primary_packet: exact-text | symbol-indexed | structural | config-content | hosted-search | graph-path
+ repo_shape: app | infra | content | game | mixed | unknown
+ search_goal: locate | references | ownership | impact | archaeology | unknown
+ scope_hint: path | package | file-type | subsystem | repo-wide | unknown
+ route_after: stay-here | debugging | log-analysis | code-refactoring | code-review | graphify
```
- Escalate with:
- - case-insensitive search when naming is inconsistent
- - file globs for language targeting
- - path constraints when the repo is noisy
- - regex only when exact text is not enough
-
- #### Lane B — Symbol / indexed search
- Use when the user needs definitions, references, or repository-wide navigation around symbols.
-
- Good fits:
- - function/class/interface definitions
- - call sites / references
- - import trees
- - public API ownership
- - symbol lookup across a monorepo or hosted repo
-
- Prefer repository-native or indexed search when available because symbol search usually beats grep for:
- - overloaded names
- - cross-language references
- - exact symbol boundaries
- - very large repos
-
- If indexed search is unavailable, fall back to exact-text patterns plus targeted file reading.
-
- #### Lane C — Structural search
- Use when syntax shape matters more than exact spelling.
-
- Good fits:
- - "all `fetch()` calls without timeout handling"
- - "React effects missing cleanup"
- - "Python functions with broad `except:`"
- - codemod prep / repeated pattern inventory
-
- Use AST-aware tools such as `ast-grep` when available. If not available, approximate with regex only when false positives are acceptable and label the lower confidence.
-
- #### Lane D — File discovery
- Use when the first task is to locate the likely file set.
+ Choose **one** primary packet for the run. If two seem plausible, pick the cheaper one that reduces uncertainty fastest.
- Good fits:
- - test files
- - config files
- - build scripts
- - route handlers
- - migrations
- - engine/editor scripts
- - content pipeline folders
+ ### Step 2: Choose the packet
- Default pattern:
- ```bash
- find . -type f | rg 'pattern'
- ```
+ | Packet | Use when | Best fits | Common tools / shapes |
+ |---|---|---|---|
+ | `exact-text` | The user knows a string, env var, route, flag, class name spelling, error text, or file fragment | literal lookups, config keys, route paths, import names | `rg`, `git grep`, editor search |
+ | `symbol-indexed` | The user needs definitions, references, or call sites | function/class/interface ownership, API tracing, monorepo navigation | LSP/workspace symbol, ctags, indexed repo search |
+ | `structural` | Syntax shape matters more than literal text | missing cleanup, unsafe pattern inventories, migration prep | ast-grep, Semgrep, Comby, tree-sitter-style search |
+ | `config-content` | The repo surface is config, content, templates, front matter, shortcodes, scenes, assets, or build scripts | Terraform/Kubernetes, Markdown/MDX sites, Hugo/Next content, game packaging/config | file discovery + exact-text + targeted scripts |
+ | `hosted-search` | The repo is remote/browser-first or cross-repo lookup matters | PR archaeology, repo you do not have locally, shareable links | GitHub/GitLab hosted search |
+ | `graph-path` | The request is really about dependency tracing or persistent structure | call graph, path tracing, architecture map, graph report | `graphify`, code graph/code map tools |
- Or use glob/file-search equivalents when available in the client.
+ Packet rules:
+ - Prefer `exact-text` when the user already has a concrete token.
+ - Prefer `symbol-indexed` for “where is this defined / referenced?”
+ - Prefer `structural` only when regex would be too blunt.
+ - Prefer `config-content` when the real surface is not classic source code.
+ - Prefer `hosted-search` when local context is missing.
+ - Prefer `graph-path` only when ordinary search is no longer enough.
### Step 3: Narrow scope before reading everything
- Apply at least one narrowing move before reading lots of files:
- - limit by directory (`backend/`, `src/`, `packages/checkout/`, `Content/`, `Assets/`)
- - limit by file type (`*.ts`, `*.py`, `*.sql`, `*.cs`, `*.cpp`)
- - limit by ownership or subsystem name
- - separate generated/vendor folders from authored code
- - prefer entry points and adapters before leaf utilities
+ Apply at least one narrowing move before reading files:
+ - limit by directory or package
+ - limit by file type
+ - separate authored files from generated/vendor folders
+ - start with entry points, loaders, config schemas, tests, examples, or build scripts
+ - in content/game repos, search metadata + template/asset surfaces before assuming code owns the answer
- When the repo is unfamiliar, find these anchors first:
- 1. app entry points
- 2. routing layer / CLI entry
- 3. configuration loading
- 4. service or domain modules
- 5. tests/examples that exercise the feature
+ Useful heuristics by repo shape:
+ - **app** → start with entry point, router/handler, config loader, test
+ - **infra** → start with module/overlay/root config, variable/schema, deployment surface
+ - **content** → start with content folder, front matter key, partial/include/shortcode/template
+ - **game** → start with runtime code, engine config, scene/asset/build script, editor/visual graph references
### Step 4: Read winners, not the whole match list
- After search results come back:
- 1. pick the likely definition / entry file
- 2. pick 1–3 important call sites or consumers
- 3. pick 1 config/test file if the behavior depends on setup or verification
- 4. read those files and summarize the flow
-
- Do **not** paste 100 raw matches unless the user explicitly asked for exhaustive output.
+ After the search packet returns matches:
+ 1. pick the most likely definition / ownership file
+ 2. pick 1–3 important consumers or references
+ 3. pick 1 config/test/example/build file when setup matters
+ 4. summarize the flow instead of pasting raw terminal output
### Step 5: Return an evidence map
- Default output shape:
+ Default response shape:
```markdown
## Search brief
- - Goal: [what I was trying to locate]
- - Lane used: exact-text | symbol/indexed | structural | file discovery | mixed
- - Scope: [repo/subdirs/file types searched]
+ - Goal: [what I was locating]
+ - Packet: exact-text | symbol-indexed | structural | config-content | hosted-search | graph-path
+ - Scope: [paths/file types/packages]
## Best entry points
- `path/to/file`: why it matters
- `path/to/other-file`: why it matters
## Key evidence
- `path:line` — what it shows
- `path:line` — how it connects
## Likely flow / ownership
- - entry → service → adapter → test/config
+ - entry → consumer → config/test/content surface
## Next route-out
- - `debugging` for diagnosis
- - `code-refactoring` for structural change
- - `code-review` for diff judgment
- - `graphify` for persistent architecture mapping
+ - stay in `codebase-search` or route to the next skill
```
- ### Step 6: Use search-mode heuristics
+ ### Step 6: Use packet-specific heuristics
#### For bug-location requests
- - start from the error string, log token, route, flag, or recent change
- - find the definition and the highest-signal consumers
- - route to `debugging` once the likely failure path is mapped
+ - start from the error string, route, flag, or recent change token
+ - locate the definition plus highest-signal consumers
+ - switch to `debugging` once the likely failure path is mapped
#### For impact analysis
- - find definition
- - find all important call sites / consumers
- - find tests, docs, and config tied to the symbol
- - explicitly separate **must-update** files from **maybe-affected** files
+ - definition first
+ - major consumers second
+ - tests/config/docs/content surfaces third
+ - separate **must-update** from **maybe-affected**
+ - route to `code-refactoring` when the user is ready to change behavior-preserving structure
- #### For code archaeology
- - look for entry points, README/docs, examples, and integration tests first
- - map the main workflow before diving into helpers
- - prefer naming/ownership explanations over exhaustive command dumps
+ #### For config/content ownership
+ - locate loader/schema/template first
+ - then find runtime consumers or referenced pages/assets
+ - call out whether ownership sits in config, content metadata, templates, or code
- #### For config hunting
- - locate loader code first
- - then locate env/example/default files
- - then locate validation or schema enforcement
- - then find runtime consumers
+ #### For structural search
+ - explain the search shape in plain English
+ - prefer AST-aware tooling
+ - if forced to approximate with regex, label the confidence limit clearly
- #### For game/tooling repos
- - separate runtime code, editor/build scripts, assets/content, and platform packaging
- - prefer subsystem boundaries over engine-wide grep floods
- - look for build configs, plugin manifests, and pipeline scripts early
+ #### For archaeology requests
+ - start from entry points, docs, examples, tests, or build scripts
+ - avoid pretending you already understand the architecture after one search
+ - route to `graphify` if the user actually wants persistent structure mapping
- ### Step 7: Route out aggressively when search is no longer the bottleneck
- Hand off when the next step becomes a different job:
- - **Root cause / reproduction / hypotheses** → `debugging`
+ ### Step 7: Route out aggressively
+ Switch when the next job is no longer search:
+ - **Root cause, reproduction, hypotheses** → `debugging`
- **Raw log triage** → `log-analysis`
- - **Behavior-preserving cleanup or codemod planning** → `code-refactoring`
- - **Whole-repo persistent structure map** → `graphify`
- - **Diff/PR judgment** → `code-review`
+ - **Behavior-preserving cleanup / codemod planning** → `code-refactoring`
+ - **Diff / PR judgment** → `code-review`
+ - **Persistent architecture graph or path tracing** → `graphify`
## Examples
### Example 1: Pre-change discovery
**Prompt:**
- > Find where auth is implemented and what files I need to inspect before changing it.
+ > Find where auth is implemented and what files I should inspect before changing it.
**Good response shape:**
- - identify entry points (middleware/router/auth service)
- - identify config/env loader
- - identify tests or integration points
- - return a compact evidence map and next files to inspect
+ - choose `symbol-indexed` or `exact-text`
+ - identify entry points, config, and tests
+ - return a compact evidence map
+ - route to `code-refactoring` or `debugging` only after the discovery step
- ### Example 2: Impact analysis
+ ### Example 2: Config/content ownership
**Prompt:**
- > Trace all call sites of `calculatePrice()` and summarize impact before refactoring.
+ > Which MDX pages still use the old pricing CTA shortcode, and where is the shared partial defined?
**Good response shape:**
- - definition file
- - major consumers grouped by subsystem
- - tests/contracts depending on it
- - must-update vs maybe-affected list
- - route-out to `code-refactoring`
+ - choose `config-content`
+ - search content metadata + shortcode/template surfaces
+ - identify source partial plus affected pages
+ - keep the answer discovery-first
### Example 3: Structural query
**Prompt:**
- > Find all async handlers that call the database without timeout or cancellation handling.
+ > Find all React effects missing cleanup. I do not want plain grep.
**Good response shape:**
- - choose structural search
- - describe match pattern
+ - choose `structural`
+ - prefer AST-aware matching
- list highest-confidence hits
- - state confidence limits if regex fallback was required
+ - label regex fallback limits if needed
- ### Example 4: Config ownership
+ ### Example 4: Game/infrastructure archaeology
**Prompt:**
- > Search this monorepo for who owns S3 config and where it is validated.
+ > Search this repo for where matchmaking region config is defined and what scenes or services consume it.
**Good response shape:**
- - config loader / schema file
- - runtime consumers
- - deployment or env examples
- - likely owning package/team/subsystem
+ - choose `config-content` or `symbol-indexed` based on repo shape
+ - separate config ownership from runtime consumers
+ - call out code + asset/build surfaces if they both matter
## Best practices
- 1. Prefer the **cheapest lane that can answer the question**.
+ 1. Choose the **smallest packet** that can answer the question.
2. Narrow scope before reading large match sets.
3. Return an evidence map, not a terminal transcript.
- 4. Separate search from diagnosis, refactoring, and review.
- 5. Label confidence when structural intent is approximated with plain text search.
- 6. Use tests, examples, and config loaders as high-signal navigation anchors.
+ 4. Cover config/content/game surfaces honestly; repo navigation is not only source-code lookup.
+ 5. Separate search from diagnosis, refactoring, review, and persistent graphing.
+ 6. Label confidence when structural intent is approximated with plain text search.
7. For monorepos, group findings by package or subsystem.
## References
+ - `references/intake-packets-and-route-outs.md`
- `references/search-modes.md`
- `references/evidence-map-template.md`
- `references/handoff-boundaries.md`
- GitHub Code Search syntax docs: https://docs.github.com/en/search-github/github-code-search/understanding-github-code-search-syntax
- Sourcegraph code search docs: https://sourcegraph.com/docs/code_search
- ast-grep introduction: https://ast-grep.github.io/guide/introduction.html
- ripgrep guide: https://github.com/BurntSushi/ripgrep/blob/master/GUIDE.md