Pinpoint
Searching is the most expensive thing a coding agent does by accident. "Debug my website" sends it through directory listings, greps and whole-file reads before it touches the fault. "The Save button on /settings does nothing; it should POST to /api/profile; the handler is in src/routes/profile.ts" sends it straight there. Every file it reads along the way is paid for again on each later turn, because it stays in the context.
1. Brief first
Before the first search, check the request for six things:
| Field |
Example |
| Where |
page, route, screen or command; file or function if known |
| Steps |
how to make it happen |
| Observed |
what happens, with the exact error text |
| Expected |
what should happen instead |
| Done when |
the check that proves it's fixed |
| Scope |
what not to touch |
- If one targeted lookup fills the gap (one grep for the button label, one look at the route table), do that.
- If it can't, and the user is around, ask one short question that names only the missing fields. One round trip costs less than an exploration spree.
- Restate the brief in two to four lines, then start at the named location. Read the smallest slice that answers the question (a function, a line range), not whole folders.
2. Map once, reuse every time
When the repo is bigger than a handful of files and has no map, write one the first time you have to explore it:
- Save it as
CODEBASE_MAP.md at the repo root, or as a small project skill. Put one line in the instruction file (AGENTS.md, CLAUDE.md, GEMINI.md) that says where it is. Don't paste the map itself into the instruction file: that file loads in every session.
- Keep it under about 150 lines. Date it.
- Most useful part: a "symptom → start here" table, so a bug report goes straight to a file.
# Codebase map (updated YYYY-MM-DD)
Run: `<dev command>` · Test one file: `<test command> <path>`
## Entry points
- `<path>`: <what starts here>
## Routes / screens → files
| Route | Handler | View |
|---|---|---|
## Feature → folder
| Feature | Folder |
|---|---|
## Symptom → start here
| Symptom | Look at |
|---|---|
## Traps
- <thing that looks right but isn't>
A stale map is worse than none: it sends the agent to the wrong place with confidence. Check that a path exists before trusting it, and update the map when you move things.
Per tool
- Claude Code and Gemini CLI take
@path in the prompt to pull a file straight in. In any tool, pasting the path does the job.
- When a wide search can't be avoided, give it to a subagent so only the findings come back to the main context. See
cheap-subagents.
Before you finish
Part of agent-skills · MIT · improvements welcome as issues.
1---2name: pinpoint3description: Turn a vague task into a pinpointed brief before searching, and map a codebase once so later tasks start in the right file. Use when a request has no location or expected result ("fix my site", "debug this", "the button doesn't work"), or when asked to map where things live in a repo.4license: MIT5---67# Pinpoint89Searching is the most expensive thing a coding agent does by accident. "Debug my website" sends it through directory listings, greps and whole-file reads before it touches the fault. "The Save button on /settings does nothing; it should POST to /api/profile; the handler is in `src/routes/profile.ts`" sends it straight there. Every file it reads along the way is paid for again on each later turn, because it stays in the context.1011## 1. Brief first1213Before the first search, check the request for six things:1415| Field | Example |16|---|---|17| Where | page, route, screen or command; file or function if known |18| Steps | how to make it happen |19| Observed | what happens, with the exact error text |20| Expected | what should happen instead |21| Done when | the check that proves it's fixed |22| Scope | what not to touch |2324- If one targeted lookup fills the gap (one grep for the button label, one look at the route table), do that.25- If it can't, and the user is around, ask one short question that names only the missing fields. One round trip costs less than an exploration spree.26- Restate the brief in two to four lines, then start at the named location. Read the smallest slice that answers the question (a function, a line range), not whole folders.2728## 2. Map once, reuse every time2930When the repo is bigger than a handful of files and has no map, write one the first time you have to explore it:3132- Save it as `CODEBASE_MAP.md` at the repo root, or as a small project skill. Put one line in the instruction file (AGENTS.md, CLAUDE.md, GEMINI.md) that says where it is. Don't paste the map itself into the instruction file: that file loads in every session.33- Keep it under about 150 lines. Date it.34- Most useful part: a "symptom → start here" table, so a bug report goes straight to a file.3536```markdown37# Codebase map (updated YYYY-MM-DD)38Run: `<dev command>` · Test one file: `<test command> <path>`3940## Entry points41- `<path>`: <what starts here>4243## Routes / screens → files44| Route | Handler | View |45|---|---|---|4647## Feature → folder48| Feature | Folder |49|---|---|5051## Symptom → start here52| Symptom | Look at |53|---|---|5455## Traps56- <thing that looks right but isn't>57```5859A stale map is worse than none: it sends the agent to the wrong place with confidence. Check that a path exists before trusting it, and update the map when you move things.6061## Per tool6263- Claude Code and Gemini CLI take `@path` in the prompt to pull a file straight in. In any tool, pasting the path does the job.64- When a wide search can't be avoided, give it to a subagent so only the findings come back to the main context. See `cheap-subagents`.6566## Before you finish6768- [ ] The work started from a named location and an expected result, not a broad search.69- [ ] If a map was written or used, every path in it was checked to exist.70- [ ] The instruction file holds only a pointer to the map, not the map.7172---73Part of [agent-skills](https://github.com/MissSophieSterling/agent-skills) · MIT · improvements welcome as issues.
MissSophieSterling