Codebase Search

Codebase Search

When to use this skill

• 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 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 should act like a packet router, not a giant search tutorial.

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.

Read these support docs before choosing the packet:

• references/intake-packets-and-route-outs.md
• references/search-modes.md
• references/evidence-map-template.md
• references/handoff-boundaries.md

Instructions

Step 1: Normalize the request

Convert the prompt into this intake shape first:

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

Choose one primary packet for the run. If two seem plausible, pick the cheaper one that reduces uncertainty fastest.

Step 2: Choose the packet

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 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

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 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 response shape:

## Search brief
- 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 → consumer → config/test/content surface

## Next route-out
- stay in `codebase-search` or route to the next skill

Step 6: Use packet-specific heuristics

For bug-location requests

• 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

• 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 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 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 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

Switch when the next job is no longer search:

• Root cause, reproduction, hypotheses → debugging
• Raw log triage → log-analysis
• 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 should inspect before changing it.

Good response shape:

• 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: Config/content ownership

Prompt:

Which MDX pages still use the old pricing CTA shortcode, and where is the shared partial defined?

Good response shape:

• 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 React effects missing cleanup. I do not want plain grep.

Good response shape:

• choose structural
• prefer AST-aware matching
• list highest-confidence hits
• label regex fallback limits if needed

Example 4: Game/infrastructure archaeology

Prompt:

Search this repo for where matchmaking region config is defined and what scenes or services consume it.

Good response shape:

• 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. 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. 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

Evidence map template

Use this when reporting search findings.

## Search brief
- Goal: [what I searched for]
- Lane used: exact-text | symbol/indexed | structural | file discovery | mixed
- Scope: [subdirs, file types, exclusions]

## Best entry points
- `path/to/file`: definition / router / loader / entry point
- `path/to/file`: important consumer / adapter / test

## Key evidence
- `path:line` — what it proves
- `path:line` — why it matters

## Likely flow / ownership
- entry → service → adapter → test/config

## Must inspect next
- `path/to/file`
- `path/to/file`

## Route-out
- `debugging` if diagnosis starts now
- `code-refactoring` if structure change starts now
- `graphify` if persistent architecture mapping is needed

Notes

• Group by subsystem in monorepos.
• Separate must-update from maybe-affected when doing impact analysis.
• Avoid dumping raw search output unless exhaustive results were explicitly requested.

Handoff boundaries

Keep in codebase-search

Use this skill when the main job is discovery:

• locate definitions, call sites, configs, tests, or entry points
• map likely ownership and impact surface
• choose the right search lane and summarize evidence

Route to debugging

Switch when the next task is:

• reproducing a failure
• isolating root cause
• testing hypotheses
• narrowing symptom timelines or recent-change regressions

Route to log-analysis

Switch when the main artifact is logs and the first task is extracting signal from them.

Route to code-refactoring

Switch when the user has already found the relevant area and now needs:

• behavior-preserving cleanup
• decomposition / extraction planning
• codemod or repetitive migration planning

Route to code-review

Switch when the main task is judging a concrete diff / PR rather than locating code.

Route to graphify

Switch when the user wants a persistent whole-repo or mixed-corpus structure map, graph.json, GRAPH_REPORT.md, or graph-backed path tracing.

Smell test

If your next output would mostly be hypotheses, fixes, or redesign steps instead of search findings, you are probably in the wrong skill.

Intake packets and route-outs

Packet chooser

Use one primary packet per run.

Repo-shape ladder

• app repo → entry point → router/handler → service/module → config/test
• infra repo → root/module/overlay → variable/schema → deployment surface → consumer module
• content repo → content file/front matter → shortcode/partial/template → build/runtime consumer
• game repo → runtime code → engine config → scene/asset/build script → editor/visual graph references

Quick route-outs

• Search finding turns into hypotheses or reproduction → debugging
• Search finding turns into cleanup or staged migration → code-refactoring
• Search finding turns into diff judgment → code-review
• Search finding turns into persistent architecture mapping → graphify
• Search finding turns into log triage → log-analysis

Smell test

If your next paragraph is mostly fixes, redesign ideas, or runtime diagnosis instead of search evidence, codebase-search has already done its job.

Search modes

Use the lightest search mode that can answer the question.

1. Exact-text search

Best for:

• known strings
• env vars
• route paths
• log/error text
• config keys
• imports you already know

Strengths:

• fastest default
• works everywhere
• easy to scope by path/file type

Failure mode:

• noisy when the same token appears across many layers

2. Symbol / indexed search

Best for:

• definitions
• references / call sites
• interfaces / classes
• public API ownership
• monorepo navigation

Strengths:

• cleaner than grep for true symbol lookup
• often better for references and large repos

Failure mode:

• not always available locally
• may not capture generated/dynamic behavior

3. Structural search

Best for:

• syntax-shape matching
• unsafe patterns
• codemod prep
• repeated framework/API usage with the same shape

Strengths:

• lower false positives when syntax matters
• better for migration prep than plain regex

Failure mode:

• more setup and tooling overhead
• language support / parser details matter

4. File discovery

Best for:

• locating config files
• migrations
• tests/examples
• engine/build scripts
• package/subsystem boundaries

Strengths:

• good first move in unfamiliar repos
• reveals structure before content search

Failure mode:

• does not explain behavior on its own

Practical ladder

1. file discovery if you do not know where to look 2. exact-text search for known terms 3. symbol search for references/definitions 4. structural search when text search is too blunt 5. targeted file reading + evidence map before any route-out