The Prompt Wasn't Wrong. The Handover Was.

A coding agent completes a task, the result is wrong, and the natural response is to blame the model.

So we rewrite the prompt, increase the reasoning effort or try a larger model.

Before doing any of that, I use a simpler test:

If I were handing this to somebody who already knew the codebase, what would I still need to tell them so they knew what to do?

That answer is the task.

Familiarity does not supply decisions

Imagine handing an experienced developer this request:

Make checkout retries more reliable.

They know the repository, its architecture and its conventions. They can find the checkout code without directions.

They still need to ask which failures are retryable, how many attempts are allowed, whether the operation can run twice safely, what the customer should see and what happens after the final failure.

Codebase familiarity cannot answer those questions because the answers are not in the code. They are product and engineering decisions.

A coding agent has the same problem. The difference is that it may choose plausible answers and continue without asking. Plausible is easy to mistake for correct.

Write the handover, not an essay

The handover does not need to be long:

Retry HTTP 429 and 503 responses up to three times using the existing idempotency key. Do not retry validation failures. Preserve the current user-visible error after the final attempt, and add tests for eventual success and exhausted retries.

That tells a capable recipient what has been decided, what must not change and how to recognise completion.

The repository should supply stable context such as commands, conventions and architectural boundaries. The handover should contain what is specific to this piece of work.

Prescribe the fix when you mean it

“Add a cache here” is not the same task as “reduce this repeated query without serving stale account data.” The first asks the agent to implement our guess. The second gives it the problem and a boundary.

A prescribed fix is fine when it is a deliberate decision. Sometimes the approach has already been agreed, must match a wider design or is constrained by work outside the repository. Tell the agent exactly what to implement.

When the fix is still only an assumption, ask the agent what it recommends first. Have it inspect the relevant code and return a small number of viable options with their trade-offs. Then choose the approach and hand back an implementation task.

That separates deciding what to build from building it. It also uses the model's knowledge of the codebase without quietly allowing its first plausible idea to become the architecture.

Even when you already favour an approach, the model can still be a useful sounding board. Ask it to challenge the proposal, identify failure modes and explain when another option would be better. You do not have to surrender the decision to benefit from a second view.

If the right approach depends on an undecided business rule, the model can expose the options but the business still has to choose.

Escalation should come after diagnosis

When a strong run fails, I ask:

• would a developer familiar with this codebase know the intended outcome?
• have I supplied the decisions they cannot discover from the repository?
• have I explained the constraints and definition of done?
• is the prescribed solution deliberate, or should I ask for options first?

If the handover still forces a capable developer to guess, a stronger model will usually produce a more elaborate guess.

Only after the task survives that check does model escalation make sense.

Use the same standard

Do not ask whether the prompt contains enough words. Ask whether it would be a responsible handover to a colleague.

They may already know the codebase. They still need to know what outcome you want, which decisions have been made and how to prove the work is finished.

Coding agents need the same thing.

Before asking for a stronger model, make sure you could hand the task to a familiar human without making them guess.