Stop Agent File Discovery: Use a Parameterized Priming Command

You open a fresh session, paste the ticket, and the agent starts grepping. It reads the wrong layer first. Then a test file it didn’t need. Then it lands on the module you knew it needed before you hit enter - and every wrong turn it took on the way is now sitting in the window, where the agent has to reason past it for the rest of the task.

This is the default mode of every coding agent: probabilistic discovery. Hand it a goal, and it works out which files matter by searching, reading, and correcting. For a codebase it has never seen, that’s the right behavior - it’s the thing agents are actually good at. But you weren’t unfamiliar. You knew exactly which three files this task touches. You just had no way to say so without typing them out by hand, every single time.

Here’s the tension underneath that. Exploring a codebase is what makes an agent’s output fit your repo instead of some generic one - the reads are how it learns your conventions, your helpers, your layout. But the moment you already hold the map, that same exploring is pure waste, and the agent has no way to tell you apart from someone who has never opened the repo. It re-earns your knowledge at full price, every time.

A parameterized priming command fixes the mismatch: it loads exactly the files a recurring task needs, in one shot, before the agent guesses at anything. On the toy example this piece works through end to end, that drops a session’s grounding cost from 12,000 tokens to 6,200 - a 48% cut. And unlike a cached exploration map, that 48% holds from session one, because there’s no explore-once cost to amortize when you never paid to discover the files in the first place.

Before any of the arithmetic below, run this on your own repo. Thirty seconds settles it.

Think of a task you do often - a recurring bug, a feature you keep extending, a job you keep debugging. Write down the two or three files it touches, from memory, before you open the agent. Then start a fresh session, paste the task, and watch what it opens first.

If the agent’s first reads match the list you just wrote, you don’t have this problem. Your repo is small enough, or well-indexed enough, that discovery is already cheap. Close the tab.

If it opens a route handler you didn’t need, a test fixture, a config file, and only lands on your list on the third or fourth read, you’re paying full search cost for context you could have handed over directly. The rest of this piece is one worked example of what that costs and how to stop paying it.

The self-test is the whole argument in miniature: if you already know the files, everything past this point is recoverable cost.

Fix one concrete case and keep it for the rest of the piece: a background job that fails on a predictable schedule, the kind you’ve debugged before. You know the shape cold. The job runs from src/jobs/nightly-export.ts. The queue it runs on is configured in src/queue/config.ts. And the retry policy - usually the actual culprit - lives in src/queue/retry.ts. Three files. You could name them in your sleep.

A fresh session doesn’t have that list. It has “the nightly export job is failing,” and it starts from zero.

Watch what a normal pass at that looks like, priced with the same instrument set Cache the Explore runs on: a search costs 300 tokens, a file read costs 2,000, and a reasoning step between tool calls costs 200. If you read that piece, the three prices will look familiar. They are the same three, reused so both posts share one price list.

Seven discrete events happen before the agent has said anything useful about the bug: two searches, two files that turn out to be the wrong layer, three files that actually matter, and a reasoning step reacting to each one.

12,000 tokens, and the diagnosis hasn’t started.

Now run the other path. A parameterized priming command already knows the three files - no searching, no dead ends, just the reads plus one reasoning step to synthesize what they say.

Put the two totals next to each other and look at where the difference comes from. Discovery: 12,000. Primer: 6,200. But the correct-file subtotal, the actual reading the task needed, is 6,000 in both columns. Identical. All of the gap, then, is the cost of getting there: the two searches, the two dead-end reads, and the difference in reasoning between the two paths. Nothing else changed.

That’s the trick, and it’s worth naming precisely because it’s easy to undersell. Call the wasteful path the scanned load: the agent finds the right files by scanning, and pays for every wrong guess along the way. Call the fix the addressed load: the agent is handed the address directly and reads only what’s at it. The names matter because the addressed load is the one technique in this series that compresses nothing. A cached map shrinks 22,800 tokens of reading into a 950-token summary. The addressed load reads the same 6,000 tokens of the same three files that the scanned load ended up reading. Nothing got smaller. The detour got deleted.

Price the detour on its own: two searches (600) plus two dead-end reads (4,000) plus the reasoning difference, the seven steps discovery pays where the primer pays one (1,400 minus 200, which is 1,200). That comes to 5,800. Hold that number, because it makes a checkable claim: the entire gap between the two columns is the detour, and nothing else.

Now subtract the totals. 12,000 minus 6,200 is 5,800. Exact match, on the pencil. The primer saves exactly the detour, all of the detour, and not one token of the reading.

The addressed load doesn’t shrink what the agent reads. It deletes the search for where to read.

Encoding that address is a slash command: a prompt template with argument interpolation, parameterized so one command serves a whole class of recurring tasks instead of one:

---
description: Prime context for debugging a background job
argument-hint: <job-name>
---

Read these before anything else:

- src/jobs/$ARGUMENTS.ts
- src/queue/config.ts
- src/queue/retry.ts

State the job's trigger, its retry policy, and the three most
likely failure points. Then wait for the symptom.

/prime-bug nightly-export drops the argument into the template, and the agent opens the same three files you’d have opened, deterministically, with a clean window. It’s already standing where the answer lives before you’ve described the symptom. Swap nightly-export for any other job on the same queue and the command still points at the right files - you wrote it once, for the whole class of bug, not for this one instance.

The shape generalizes past bugs. A /prime-feature command might load a module’s implementation, its service layer, its tests, and its design doc, so a teammate who has never touched billing gets your exact grounding for free. A /prime-migration might load the schema, the latest migration file, and the ORM models that read them. Each one is a different piece of codebase knowledge you already carry, turned into something you type instead of something you re-derive.

This convention already has a name in the wild. /prime, an un-parameterized version of the same idea, is common enough in the Claude Code community that people write whole posts about not re-typing it by hand every session. What’s here is the same instinct, parameterized so it serves a family of tasks instead of a single memorized list.

A command is just a memorized answer to “which files,” made reusable and shared.

A few objections form immediately, so answer them here rather than parking them for later.

Isn’t this just @-mentioning the files? Most agents let you drop files into context by hand - an @-mention, a drag, a paste. If you already know the three files, why not just name them in the chat? Because a mention is a keystroke you re-spend every session, and it doesn’t compose. The command is parameterized, so one /prime-bug serves every job on the queue, where a mention serves one conversation. It’s versioned, living in the repo next to the code it describes. And it’s shared: a teammate who has never touched the export job gets your exact grounding for free, the first time they type the command. Mentioning files by hand is the right move exactly once; the moment the same set comes up a second time, you’re re-typing knowledge you could have committed.

Isn’t this what a repo index already does? A growing number of tools index the repo semantically and rank files by similarity to the task - a form of search, just a better-informed one. That’s a real improvement over grep, and it’s still search: it returns files it thinks are relevant, ranked by a score, and the agent still has to read a few candidates and decide. A priming command is addressed rather than ranked: an index guesses which three files matter; you already checked, so you tell the agent which three files matter. Ranked search is for when you don’t know the answer yet. Addressed loading is for when you do.

Isn’t this the same as caching the repo map from an exploration pass? That’s a genuinely different technique for a genuinely different case. Cache the Explore is for when you don’t already know the layout - you pay for one exploration pass, write down what it found, and every later run reads the summary instead of re-exploring. A priming command is for when you already carry the file list in your head before the agent starts. Neither replaces the other; they answer different versions of “do I already know this.”

What about MCP’s own primitive for this? If you’re building for multiple agent tools rather than one, the same idea exists at the protocol level: MCP defines “prompts” as its user-invoked, parameterized workflow primitive, sitting next to resources and tools. A priming command is one worked instance of that primitive. Nouns, Verbs, and Slash Commands covers the full three-way split; this piece is the single-technique version of one of them.

Isn’t this the same as pushing search into a cheap subagent? Stop Reading Your Codebase in the Window relocates the scanned load into an isolated, cheap-model subagent so it doesn’t pollute your main window and costs less per token. That’s a real fix when search is still necessary. A priming command removes the search itself - there’s no subagent to isolate it into, because there’s nothing left to search for.

Everything that competes with the primer either keeps a search going or spends a keystroke every session. The command is the one move that commits the address.

Some context is true no matter which task you’re running: the build command, the fact that all timestamps are UTC, that legacy/ is frozen. Pinning that into a priming command would be redundant - it belongs one level up, in your rules file, read on every session automatically, the standing-context primitive Write It Down Once argues for:

## Always-true context
- Run tests with `pnpm test`, never `npm test`.
- All timestamps are UTC. Never localize in the data layer.

## Where things live
- Background jobs: `src/jobs/`, queue config in `src/queue/`.
- Use `/prime-bug <job-name>` before debugging one.

That last line is the hinge: the rules file describes standing context and points at the commands that load situational context on demand. Both live in your repo as plain files, version-controlled next to the code they describe - and because AGENTS.md has hardened from a single tool’s convention into a cross-vendor standard, that grounding travels with them. A teammate’s agent inherits the same rules and the same primer the moment they pull, whichever tool they run.

This is a different axis from hierarchical rules, which auto-load directory-scoped convention files based on whatever the agent is already touching - passive, triggered by the path it’s on. A priming command is active: you fire it before the agent has touched anything, for one named recurring task, not for whichever directory it happens to wander into.

Rules answer “what’s always true.” A priming command answers “what does this specific, recurring task need,” on command.

Here’s the toy scaled across a batch of sessions on the same recurring task:

Every row lands at 48.33%. There is no negative first row to climb out of; the line is flat starting with the first session. That’s the tell that this is a different mechanism from a cached map, not a variation on one: there’s no cost to amortize, because nothing was paid once and spread across later runs. The three file paths were free to write down. They were already in your head.

A break-even table has a first row you have to survive. This one doesn’t have a first row to survive.

Two failure modes are worth taking seriously, because the technique earns nothing if you ignore them.

The primer rots. A priming command hardcodes paths, and hardcoded paths drift. Rename retry.ts to backoff.ts, split a file, move a module, and the command keeps confidently loading what’s no longer there - either it errors out, or worse, it loads a partial set with a false sense of completeness, which is exactly the polluted-window problem it was supposed to prevent. A confidently wrong primer is worse than no primer, because the agent has no reason to doubt it. The discipline is to treat the command as code that describes code: when you refactor a module’s layout, the primer is part of the blast radius, updated in the same commit, so a reviewer who sees the old path in the diff has a shot at catching the rot before it ships. Your AGENTS.md Is Write-Once Agent Memory covers the sibling version of this problem for rules files; the file-selection version is the same discipline, applied to a shorter, more specific document.

Discovery is still correct when you’re actually lost. Nothing here argues for never letting the agent explore. Probabilistic discovery is the right tool for a bug in code you’ve never touched, a dependency you’re seeing for the first time, an integration whose seams you can’t predict. Forcing a deterministic primer onto unfamiliar code is guessing badly in advance, dressed up as certainty you don’t have.

There’s a third boundary worth stating plainly, because it’s the one that makes this piece different from its closest sibling rather than a rehash of it. Cache the Explore has an honest bad-trade case at session one: on a single run, its disposable map is a straight loss, because you pay to explore once and then pay again to write and read a summary nobody needed twice. The addressed load has no equivalent bad-trade case at session one. Its only cost is the one-time human effort of typing out a file list you already carry in your head - there’s no meta-cost of writing a disposable map, because there’s no map, just the three paths you already knew.

Losing state across a long, multi-session build is a different problem entirely, covered by The Relay, Not the Window and Treat the Plan File as External Memory, and scope drift on what you’re building in the first place is covered by Destination and Journey. None of those are about which files to read first for one task; they’re about carrying progress or intent across many sessions.

The only cost this technique has is the one you already paid, once, just by knowing your own repo.

Put the result back on the table one more time. 12,000 tokens of probabilistic discovery, 6,200 of addressed load, 5,800 saved, every single session, starting with the first one. That’s the spoiler claim from the top of this piece, reconciled: a 48% cut that doesn’t need five runs, or even two, to be worth it. Row one already wins here, unlike a cached exploration map, because nothing was paid once and amortized. The human’s knowledge was free to write down, and the primer just skips the detour every time it’s used.

Three things this piece hands forward instead of resolving. The rot problem named above is real and unfinished: a priming command is a committed artifact with no built-in staleness check, the same shape as a dated research file, and the same fix likely applies - a hook that fails the run when the primer’s file paths don’t resolve, rather than trusting a human to notice before the agent does. There’s a newer question alongside it: packaging a primer as a skill instead of a bare slash command bundles the procedure with the file list into one shareable, versioned unit, rather than a prompt template a teammate has to know exists. And there’s a third, further out: research on automatic, model-driven context selection, letting the model decide and prune its own window, is active work in 2026. Whether that automation solves the problem this piece solves, or just reintroduces the guess under a different name, running inside the model instead of in front of it, is the open question a probabilistic-discovery generation of tools is about to answer.

Discovery is for the unknown. For everything you already know, stop making the agent guess, and stop making it scan. Hand it the address.

About the numbers. The token prices (search 300, read 2,000, reasoning step 200), the two searches, the two dead-end reads, and the three correct files are toy inputs, chosen to be hand-checkable rather than measured from a real session. The prices are reused from Cache the Explore so the two pieces share one price list, and the 22,800 and 950 figures quoted in the compression comparison are that post’s toy numbers, carried across for the same reason. Every total, the 5,800 saved, the exact-match check, and every row of the master table follow from those six inputs by arithmetic and were verified with a script before publishing. Swap in your own token counts for your own repo and the shape holds: the correct-file subtotal stays identical across both paths, the detour is still exactly what gets deleted, and the percentage saved is still flat from session one.

For the mechanics per tool, see Slash commands for building the primer, Rules for the standing context it complements, and Configuration for where these files resolve.