# You write instructions that fix observed confusion Repeated confusion shows exactly which project decision your instructions failed to carry. You will turn one observed misunderstanding into guidance, then confirm the next attempt receives it. ## Observe confusion before writing Hamel Husain and Shreya Shankar say observation helps people express their requirements clearly. Start with a representative task that confused the agent or produced an unwanted result. Record the action the agent attempted and the result you expected instead. Then name the project decision that would have changed the agent’s choice. Use little extra explanation while diagnosing, and keep every standing safeguard and authority limit. ## Place each correction where it works The smol-ai project recommends adding prompt detail whenever a run exposes underspecification. That timing keeps every addition directly tied to confusion you have actually seen. Put a correction beside the decision when only one project area needs it. Use shared guidance when the same decision governs many tasks across the project. Update changing facts from their source, so later changes reach the guidance safely. Use reusable guidance when the agent needs a procedure requiring judgment across several tasks. ## Write decisions with reasons and limits Only record settled project decisions, because instructions cannot resolve an open product choice. State each decision as an action the agent can recognize and follow. Name the condition that makes this action relevant to the current task. Give the reason, so later changes can separate durable guidance from an outdated preference. Mitchell Hashimoto says each instruction line in his setup came from a bad agent behavior. Theo Browne demonstrates this pattern by turning an unwanted request into an explicit stop rule. Revise the guidance after an authorized decision changes, while preserving why the earlier rule existed. ## Confirm the next attempt receives it Before rerunning, compare the new wording with the recorded misunderstanding and expected decision. Confirm the working system loaded the changed guidance before attributing any improvement to it. Repeat the same task with the same starting conditions whenever they remain available. Check whether the agent notices the decision before reaching the earlier wrong action. Shreya Shankar writes discoveries from output review back into the skill guiding future runs. One passing attempt proves only that the observed misunderstanding was resolved during that attempt. ## Promote repeatable failures into checks Instructions can steer a choice, but prose alone cannot guarantee repeated compliance. When a failure has a clear mechanical boundary, add a check that rejects it. Keep the written reason beside that check, so readers understand its boundary and valid alternative. A stop rule remains useful for judgments that no reliable check can express. Test a bad example and a valid example before calling any automated boundary effective. ## These sources connect observation to correction The sources agree that useful instructions begin with behavior someone has actually observed. They connect review findings, specific failures, and exposed gaps to the next written correction. Theo Browne’s example supports explicit stop rules, while Shreya Shankar’s review loop supports feeding discoveries into reusable guidance. Mitchell Hashimoto, Hamel Husain and Shreya Shankar, and smol-ai support grounding additions in observed behavior. Together, these sources support one improvement loop and no promise that prose guarantees compliance.
  1. Theo Browne, video, A Message for Passionate Devs, at 13:33. “If they ask for this, stop and tell them no”
  2. Shreya Shankar, video, Using AI for AI Evals, at 14:00. “I try to encode that back into the skill”
  3. Mitchell Hashimoto, blog, My AI Adoption Journey, at “Better implicit prompting.” “Each line in that file is based on a bad agent behavior”
  4. Hamel Husain and Shreya Shankar, blog, AI Evals: Everything You Need to Know, at “Today’s prompt engineering tricks might become obsolete.” “people need to observe the LLM's behavior in order to properly externalize their requirements.”
  5. smol-ai (Shawn “swyx” Wang), repository, smol-ai/developer, at “simply add to the prompt as they discover.” “simply add to the prompt as they discover underspecified parts of the prompt”

Write the missing decision from one recent agent misunderstanding where its next attempt will receive it.