Scoping a Prompt

The prompt is the smallest piece of the stack, and the one an FDE makes the most decisions about per customer. This lesson is about the discipline behind those decisions.

Three places a piece of information can live. The prompt. The retrieval layer. A tool. Each has a cost and a failure mode, and the mistake is not usually "wrong answer in the right place" — it is "right answer in the wrong place."

The three places and what they are for

The test for where a piece of information belongs is three questions. Is it the same on every turn? Prompt. Does it live in a corpus you query? Retrieval. Does it require a round trip to a system that might answer differently? Tool.

An FDE learns to feel the wrong placement. A tool call to a system whose answer never changes is a waste of a round trip. A retrieval over a document that fits in 500 tokens is overhead. A system prompt with a customer's last earnings report in it is paying the full price every turn for data one question in a hundred needs.

Point at sources, do not paste them

Pasting pins the information to the moment you pasted it. Referencing lets the information stay where it lives, which is where the owner updates it. On a customer deployment this difference is enormous. A pasted policy document is wrong from the next revision onward; a reference to the policy document is right as long as the file is.

The same principle holds for the trace of an incident: do not paste the stack trace into the prompt, point at the Sentry issue and let the tool read it. What you lose in immediacy you gain in the one thing that matters — the model sees the current version.

Describe the symptom, not the diagnosis

The second habit, and the one FDEs steal from doctors. A prompt that says "fix the N+1 query in the invoice loader" has committed to a diagnosis before the model has looked at the code. If the real problem is a missing index, or a cache invalidation bug, or a schema change that broke a join, the model will still go looking for a loop to collapse.

A prompt that says "the invoices page is timing out on workspaces past 50k rows; here is the log line — figure out what is slow and fix it" leaves the search space open. The model may land on the N+1 if that is in fact the problem, and it may land somewhere you did not think to look.

The habit does not say "never diagnose." It says the diagnosis belongs after the exploration, not before. Lead with what you observed. Follow with what you tried. End with the ask.

The vague prompt on purpose

There is one case where the discipline flips, and it catches new FDEs out. During discovery — the first week on a new customer surface, the triage of an unfamiliar codebase, the "what could we build here" conversation with a stakeholder — the right prompt is vague.

"Look at this repository and tell me which three things would most benefit from an agent" is not a tightly scoped request. It is not meant to be. A tight prompt would return the options you already had in mind, which is not what you asked for. A vague prompt invites breadth, and breadth is the whole point.

The rule is: match the prompt to the question. Narrow when you know what you want. Wide when you are hunting for what you do not know.

A corrected prompt

prompt review

1. >You typed: Fix the N+1 query in the invoice loader. We think it's in the join on line 47.

2. WhyEverything about this is a diagnosis. The model will go looking for a loop to collapse, and if the real problem is somewhere else, it will find a plausible answer anyway.

3. >You typed: The invoices page is timing out on workspaces past 50k rows. Here's the log: `[timeout] GET /invoices after 30s`. The slow trace is attached. Read the loader at src/exports/invoices.ts and find what's actually slow — don't assume it's a query.

4. WhySymptom, not cause. A specific input (50k rows), a specific signal (the log line), a specific starting point (the file), and an explicit instruction not to prejudge.

5. Claude replied: I see the timeout. Reading src/exports/invoices.ts...

6. Claude ran: Read src/exports/invoices.ts

7. Claude ran: postgres - explain analyze

8. Claude replied: The N+1 is real but it's not the bottleneck. The sort is scanning a 2.1M-row table without an index. Fix is a composite index on (workspace_id, created_at).

9. WhyA diagnosis the first prompt would not have found.

What to take away

Three places information can live, and each has a test. Same on every turn is the prompt. Looked up per question is retrieval. Fetched over a boundary is a tool. Reference sources instead of pasting them, so the prompt does not go stale. Describe the symptom, not the diagnosis, so the model has room to disagree with you. And when you are hunting for what you do not know, send a wide prompt deliberately — the rule bends for discovery and nowhere else.

Next: structured output and tool schemas, which are the same mechanism with a different name.