Selecting built-in tools

Choose the built-in tool for the task

• Grep searches contents — function names, error messages, import statements.
• Glob matches paths — files by name or extension, such as **/*.test.tsx.
• Read and Write handle whole files.
• Edit makes targeted modifications by matching unique text.

Grep and Glob are the pair most often confused. One asks "which files contain this?", the other "which files are named like this?".

Bash sits beside these and does a different job: none of the file tools runs anything, so a test command, a build, or git belongs there. Searching or editing through a shell instead gives up structured results for console text that varies by machine, and a stream-editor rewrite changes every match with nothing to confirm first.

When Edit fails

Edit depends on finding unique anchor text. When the text it is given appears more than once, it can't safely decide which occurrence you meant, and it fails.

That's not a dead end, and it has two fixes. Which one you want is a question about intent, not about the error:

• Expand the anchor. Add surrounding lines until the text matches exactly one place. Use this when one particular occurrence should change.
• Set replace_all: true. Use this when every occurrence should change, which is the usual case for renaming something.

The same failure and both remedies, against one file:

anchor "const timeout"                        3 matches -> fails
anchor "const timeout = 30"                   1 match   -> that one changes
anchor "const timeout", replace_all: true     3 matches -> all three change

The second line and the third line answer different questions. Nothing in the failure message tells you which one you meant, because only you know that.

Reaching instead for Read and then Write rewrites a whole file to change one line, and puts every other line at risk of coming back altered. A narrow edit that failed is a reason to aim it better, not a reason to widen it.

Explore incrementally

Reading many files at once fills the context window with information that may not matter. Start from a known entry point and expand only as the investigation requires.

Work forward instead:

1. Grep for an entry point — a route, a handler, an error message from a report.
2. Read that file.
3. Follow its imports, reading only what the trail actually requires.

This process keeps the investigation focused on files connected to the task.

Tracing through wrappers

Usage tracing gets harder when a module re-exports things. Do it in two steps: identify all exported names first, then search for each name across the codebase. Searching only for the original name misses every call that goes through the wrapper.