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.

Context is not free. 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 verified, and check that it actually helped. A long, generic AGENTS.md is worse than a short, sharp one.

Two corrections come up most often with this template. Record whichever one fits the mistake you saw, verbatim:

• It dropped the orphan lines. An INNER JOIN to products silently discards the 15 order lines whose product id has no match, and 3,637.89 of real revenue with them - the same defect behind the 1,396.89 gap you saw in the 2024 numbers. 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 the wrong revenue column. 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."

Your task

Pick something the agent got wrong, or quietly decided without you, in the last three lessons - your audit notes in queries/audit_v1.md are the shopping list. Add the one-line rule 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 changes what the agent reads, not the data. 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.

Check your understanding

• 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?

Do it with your agent

Say next lesson and your agent teaches this, asks you these questions, then sets the task above. Do it by hand, then say review my work - it checks your work against a rubric and tells you what to fix or marks the lesson done.