Fix the context, not the prompt

Fix it once, for everyone

When an agent gets something wrong, the instinct is to rewrite the prompt. That fixes one conversation. Writing the correction into the repository fixes every future conversation, for you and for anyone else who works here.

A correction can live in three places, in increasing durability:

1. The column description in the asset definition. The agent reads it before writing SQL, so a good description steers the next query.
2. The AGENTS.md file at the project root. This is instruction the agent reads every session, so it is the place for rules that span the whole project.
3. A quality check that makes the mistake impossible to ship. The most durable of the three, because it fails loudly instead of relying on the agent to remember.

Make a real correction

Pick something the agent actually got wrong, or quietly decided without you, in the last three lessons. Your audit notes in queries/audit_v1.md are the shopping list. With this template two candidates come up most often:

• It dropped the orphan lines. An INNER JOIN to products silently discards the 15 order lines whose product id has no match - the 1,396.89 gap you may have met in the checkpoint two lessons ago. The rule to record: "When joining order_items to products, use a LEFT JOIN and bucket unmatched lines as 'Unknown'. An INNER JOIN silently drops 15 lines of real revenue."
• It picked a revenue column without flagging the choice. If it used unit_price where net_price was meant, record: "Revenue is quantity * net_price. unit_price is the list price before discount and is not revenue."

Add your one line to AGENTS.md. Then sharpen the description on the relevant column in pipeline/assets/order_items.sql so the next query starts from better information. Editing a description is safe: it changes what the agent reads, not the data the query generates. Re-ask the original question and watch whether the mistake returns.

If your agent made neither mistake, that is worth noticing too - this template already carries unusually good context, which is the point of the lesson. Write the correction for whatever it did get wrong, however small, so you practise the mechanism.

Context is not free

Be honest about how much this buys you. Research on agent-context files found that careful, human-written notes improve task success by only a few percent, and that machine-generated context can make results worse while adding around 20 percent to cost. So context is not automatically good.

The rule that follows: write context for a specific failure you observed, keep it short, and check that it actually helped. A long, generic AGENTS.md is worse than a short, sharp one.

Ask your coding agent

Checkpoint

You should be able to answer these:

• Name the three places a correction can live, in order of durability.
• Why does rewriting a prompt fix less than writing to the repository?
• After your correction, did the agent produce the right revenue column, and how did you confirm it?