Don't Send Your Agents on a Scavenger Hunt

The issue template said: “Find the handler that processes incoming webhooks and add retry logic.” I’d written that. A planning agent had stamped it into a GitHub issue, and a dispatched coding agent — one of my automated developer workflows, basically a Claude Code session that picks up an issue and writes the code — had just spent its first ten minutes grepping the repo to find the thing I already knew the location of.

Here’s the setup, for anyone who doesn’t live in this stuff. I have one agent that plans work and writes it up as GitHub issues, and other agents that grab those issues and actually implement them. Think of it like a senior dev writing tickets for a team of juniors who’ve never seen the codebase before. The ticket is the only context they get.

And my tickets were bad. Not wrong — bad. They said things like “search for where Y gets called” and “locate the X service.” Every one of those phrases is a little scavenger hunt. The dispatched agent has to go discover what the codebase looks like before it can change anything.

I’d been treating the planning agent as the smart one and the coding agents as the workers. But the planning agent was writing instructions like a manager who’d never opened the repo. The first time I watched a session burn its early turns re-deriving a file path, it clicked: I was paying twice. Once when I vaguely gestured at the code, and again when the agent rediscovered what I gestured at.

So I changed what “planning” means. Before any issue template gets written, the planning step now opens the actual repo. It greps. It reads the files. It pins down the specific path, the function name, the line where the bug probably lives, and a guess at the root cause. Then it writes the ticket — with those concrete details baked in.

The difference is night and day. An agent handed src/webhooks/handler.ts, the function name, and “retries probably need to wrap the dispatch() call around line 80” gets to work immediately. An agent handed “find the webhook handler” spends its freshest reasoning on archaeology.

Why does this matter so much? Because an agent’s context is most valuable at the start, when the window is empty and the model is sharpest. Spend that budget on the actual problem, not on rediscovery. Investigation is cheap to do once, upfront, and expensive to repeat on every dispatch.

# resolve the vague "webhook handler" into a real path + line
rg -n "dispatch\(" src/webhooks --type ts
rg -n "export (async )?function" src/webhooks/handler.ts

## Target
File: src/webhooks/handler.ts
Function: handleIncoming() (line ~74)
Root cause: dispatch() at line 80 has no retry; transient 503s drop the event.

## Task
Wrap dispatch() in a bounded retry (3 attempts, exp backoff).

If you orchestrate coding agents, audit your own templates for scavenger-hunt verbs — “find,” “locate,” “search for.” Each one is a task you’ve punted to a worse position than yours. Do the grep yourself, hand over the coordinates, and let the agent spend its first move on the actual work.