tools-code-search

---
name: "tools-code-search"
description: "Local search is the first evidence pass. It discovers where the architecture is implemented before heavier tools spend time proving graph or semantic facts."
license: "MIT"
---

# Code search and targeted reading

Local search is the first evidence pass. It discovers where the architecture is
implemented before heavier tools spend time proving graph or semantic facts.

Evidence dimensions: **discovery** and lightweight **structural** context.

## When to use

Use during the system-map step and whenever a finding needs scoped file:line
support before graph, AST, LSP, or language-tool confirmation. Good questions:

- Where are the entrypoints, deploy units, public interfaces, and package roots?
- Which files mention a domain concept, config key, route, queue, or dependency?
- Which modules import a boundary package or framework type?
- What docs, ADRs, manifests, or ownership files describe intended structure?
- Which exact files should the review read next?

This skill supports `architecture-review`; it does not assign architecture scores
or make findings by itself.

## Commands

Run from the repo root. Prefer `fd` for paths and `rg` for text. Use the
runtime's file-read tool for targeted reads after search narrows the scope.

```sh
# High-signal structure and intent files
fd -H '(^README|CONTEXT|ARCHITECTURE|adr|decisions|ownership|CODEOWNERS|package.json|pyproject.toml|go.mod|Chart.yaml|kustomization.yaml|Dockerfile|\.github)' .

# Files by language / package marker
fd 'package.json|tsconfig.json|pyproject.toml|requirements.txt|go.mod|main.tf|Chart.yaml|kustomization.yaml'

# Exact concepts, routes, config keys, or dependency names
rg -n --hidden --glob '!{.git,node_modules,dist,build,vendor}/**' 'Order|Payment|Auth|Session|Repository|Controller|Handler|typeorm|sqlalchemy|kafka|redis'

# Import/dependency hints before AST or graph tools
rg -n --glob '!{.git,node_modules,dist,build,vendor}/**' "from ['\"]|import |require\(|package "

# Git-tracked scope, useful for generated/vendor exclusion
git ls-files

# Change hints when GitNexus is missing or stale
git log --name-only --pretty=format: -- <path> | sort | uniq -c | sort -nr | head
```

Prefer `git grep -n <pattern>` when the review should ignore untracked/generated
files and only search the versioned source. If the target is not a git repo,
record that limit and use scoped `fd` / `rg` instead.

## Evidence output

Record:

- `dimension`: discovery or structural context.
- `source`: exact command, pattern, and searched scope.
- `facts`: file:line refs and the code/doc fact each ref proves.
- `limits`: excluded paths, missing tools, generated/vendor noise, or partial checkout.
- `next_tool`: specialized follow-up if the claim needs AST, graph, LSP, language, or history proof.

## Confidence impact

- A scoped `rg`/`git grep` hit with a targeted file read is direct discovery or
  structural evidence. Cite the command and file:line.
- A clean exact-text search is evidence only for that literal pattern in the
  searched scope. It does not prove absence of a concept, dependency, caller, or
  boundary leak.
- Directory shape and file names are weak evidence of intended modules. Use them
  to plan deeper checks, not to score architecture quality.

## Failure and missing-tool handling

- `rg` or `fd` missing → record the discovery dimension `tools_missing`; fall
  back to `grep` / `find` and say the search is slower/coarser.
- Generated/vendor noise overwhelms results → narrow with `git ls-files`, path
  globs, or package roots; do not paste raw dumps.
- A repo with sparse checkout, shallow history, or generated sources has partial
  discovery coverage. Record the limit before drawing conclusions.

## When to stop

Stop when you have enough paths to read and enough facts to choose the next
specialized tool. Return a short read-next list, not a full repository index. If
the question needs structural pattern proof, switch to `tools-ast-grep`; if it
needs real references/callers, switch to `tools-lsp-tree-sitter` or
`tools-codegraph`; if it needs co-change or volatility, switch to
`tools-gitnexus`.

## Hard rules

- Read only the files or ranges that answer the current question.
- Cite command + scope + file:line for evidence.
- Never score or assert boundary integrity from directory shape or text search
  alone.
- Separate facts found by search from hypotheses that need graph, LSP, language,
  or history confirmation.