← Tidelines/Best practices

Why your agent swaps oat milk for dairy

An order assistant that swaps a dairy-free customer’s oat milk for whole milk followed its prompt to the letter. The rule said offer a similar item, the exception was a fact about the app, and the allergy line gave it nothing to do. Here is the defect, and why scoping the rules is not enough.

by TypeGlish team6 min read#best-practices
Similar is not safe.

TL;DR Your grocery agent swaps oat milk for dairy because the prompt tells it to offer a similar item and leaves “similar” to the model; scoped rules cannot fix it, because an item can be out of stock and marked no substitutes at once, so move the decision into a substitutes tool that owns allergies, pack size, price and the no-substitutes flag.

Grocery substitutions are the one place an order assistant makes a product decision on the customer’s behalf. Get it right and nobody notices. Get it wrong and the dairy-free customer has a carton of whole milk on the doorstep, and a screenshot of the chat that promised it.

§1The symptom

An illustrative exchange, of the kind a grocer’s QA team flags in the first week of a launch:

the transcript - Saturday’s delivery✗ wrong substitute
customer:  Oat milk is showing out of stock for Saturday. What will you send instead?
assistant: Sorry about that! I've noted a similar item for you: Harbridge whole milk,
           2 litres, same price. You won't be charged any more.
Same pack size, same price, same word. To the model, that is what similar means.

Nothing in that reply breaks a rule the agent was given. It offered a substitute, kept the size, held the price. It also undid the only reason the customer was buying oat milk, and if the customer had marked the item no substitutes in the app, it ignored that too.

§2The section that wrote it

Harbridge Market delivers groceries in one-hour slots. Its order assistant’s substitution section came from the help page and a note from the trading team:

naive.tg - the substitutions section✗ D (64/100)
# Role
You are the order assistant for Harbridge Market, an online grocer that delivers in one-hour slots.

# Substitutions
If an item is out of stock, offer the customer a similar item instead.
Customers can mark any item as "no substitutes" in the app.
Respect the customer's substitution preferences where possible.
Substitutes should be the same size or larger, at the same price.
Be careful with allergies.
$ typeglish review naive2.tg
naive2.tg — D (64/100) → A (97) projected if every fix below lands  check: 0 error, 1 warning, 6 info  tiers: base+z3

  FIXES  ranked by projected gain
  +12  put a "@@ why" note above L2 L5 L6 L7 L8 L9 — annotation 0 → 100
  +6   commit the 2 soft statements ("any" on L6, "where possible" on L7) to MUST / NEVER / ALWAYS / REQUIRE / ENSURE — or keep the word if it is a permission by design — up to hardness 100
  +4   fix the 1 prompt/unmeasurable finding (L9) — A rule with no concrete, checkable action or bound.
  +3   lead with a modal (MUST / NEVER / SHOULD) on L9 — 1 rule becomes visible to the checker
  +2   give L9 an observable action or a bound ("at most 3 sentences")
  +2   fix the 2 prompt/unregistered-doer findings (L6 L8) — A bare generic doer (Users should ...) never enters the world model - the imperative or a definite party registers wh…
  +2   fix the 2 prompt/unintroduced-definite findings (L8) — A definite retrieves a card the document never introduces (Open the store. - which store?) - introduce the head on an…
  +1   fix the 1 typeglish/if-then finding (L5) — A conditional (IF / WHEN / UNLESS / WHILE / …) opened without its THEN — an ADVISORY by the owner’s ruling (2026-08,…
  +1   fix the 1 prompt/hedging finding (L7) — A hedge (try to, if possible) softens an instruction; commit to a modal.

  RULES  2 of 3 rule-shaped lines read · 1 unmeasurable
    L9   ~ unmeasurable  Be careful with allergies.
                         no observable action or bound, so nothing can check compliance → name a concrete action or a bound ("at most 3 sentences")

  FINDINGS
  naive2.tg:5:1  info   typeglish/if-then  IF needs a THEN — write IF <condition> THEN <action>.
  naive2.tg:6:1  info   prompt/unregistered-doer  A bare generic doer never enters the world model - instruction to the agent, or background about users? Use the imperative if the agent acts, or a definite party ("The user should ...") to register the doer.
  naive2.tg:7:49  info   prompt/hedging  Hedging — "where possible" turns this instruction into a suggestion the model may skip. Delete the hedge, or commit to a modal (MUST / NEVER / SHOULD).
  naive2.tg:8:1  info   prompt/unintroduced-definite  "the same size" retrieves something this document never introduces - a model must guess which size is meant. Mention a size on an earlier line, or anchor it here ("their size", "the size you ...").
  naive2.tg:8:1  info   prompt/unintroduced-definite  "the same price" retrieves something this document never introduces - a model must guess which price is meant. Mention a price on an earlier line, or anchor it here ("their price", "the price you ...").
  naive2.tg:8:1  info   prompt/unregistered-doer  A bare generic doer never enters the world model - instruction to the agent, or background about users? Use the imperative if the agent acts, or a definite party ("The user should ...") to register the doer.
  naive2.tg:9:1  warn   prompt/unmeasurable  Unmeasurable rule — "be <quality>" names no observable action, so nothing can check compliance. Name a concrete action, or move it to a prose block (persona prose is allowed to be soft).

  TESTS  no $TEST cases — add one beside a rule; `test --dry` validates it offline
Every line a shopper would nod at. Three of them are rules, the checker can read two, and the one about allergies is a mood.

Read it as the model does. Line 5 is the instruction with a verb in it: offer a similar item. Line 6 is a fact about the app, not about the agent. Line 7 respects preferences where possible, a hedge the model is free to resolve against the customer whenever offering something feels more helpful. Line 9, be careful with allergies, gives the model nothing to do, and the checker’s prompt/unmeasurable warning says exactly that. Under pressure to be helpful, line 5 wins every time.

§3Two rules, one oat milk

The obvious repair is to harden line 7 into a rule. Written bare, the default and the exception are a straight contradiction, and the checker refuses them:

bare.tg - the default and the exception, unscoped✗ build refused
# Role
You are the order assistant for Harbridge Market, an online grocer that delivers in one-hour slots.

# Substitutions
- ALWAYS offer a substitute.
- NEVER offer a substitute.
$ typeglish check bare.tg
bare.tg:5:1  error  logic/contradiction  Conflicts with line 6. Logical conflict — "offer a substitute" is both required and forbidden. Keep one, or scope the two rules so they cannot both apply (IF <condition> THEN ...).
         ↳ line 6: - NEVER offer a substitute.
bare.tg:6:1  error  logic/contradiction  Conflicts with line 5. Logical conflict — "offer a substitute" is both required and forbidden. Keep one, or scope the two rules so they cannot both apply (IF <condition> THEN ...).
         ↳ line 5: - ALWAYS offer a substitute.

✗ 1 file — 2 error, 0 warning, 0 info

So you take its advice and scope them. The out-of-stock rule gets a WHEN, the no-substitutes rule gets an IF, and the build goes green:

overlap.tg - both rules scoped✓ clean
# Role
You are the order assistant for Harbridge Market, an online grocer that delivers in one-hour slots.

# Substitutions
- WHEN an item is out of stock THEN MUST offer a substitute.
- IF the customer has marked the item no substitutes THEN NEVER offer a substitute.
$ typeglish check overlap.tg
✓ 1 file — 0 error, 0 warning, 0 info
Clean, and still wrong for the oat milk. It is out of stock and marked no substitutes, so both conditions hold at once.

This is the anti-pattern. The checker’s own fix text says scope the two rules so they cannot both apply, and these two can. Whether one item is both out of stock and marked no substitutes is runtime data the checker never sees; it has no way to know the conditions overlap. The model, holding a MUST and a NEVER for the same carton, picks one, and the MUST has the more helpful-sounding verb. The same shape broke the grieving-customer sign-off in Why your agent tells a grieving customer to have a great day, and Your prompt is a default and its exceptions argues every prompt is full of it.

You could keep layering conditions. The better fix is to stop asking the prompt to hold the flag at all. Whether an item may be substituted is a property of the order line, and the order system already stores it.

§4Similar is a judgement, so give it to the catalogue

A similar item is the deeper defect. A language model’s idea of similar is mostly the name and the category: oat milk and whole milk share a word and a shelf. Your catalogue knows things the name does not, the dietary tags, the allergens, the pack size, the price. The same mistake shows up on the out-of-stock page in Rewrite: back in about two weeks, where similar turned out to be a compatibility claim.

So the substitution decision moves into a tool. find_substitutes takes the item and any allergy the customer has named in the chat, and returns the allowed substitutes: none that clash with the customer’s saved allergies or dietary tags, none smaller, none dearer, and an empty list for a no-substitutes item. The prompt keeps four short jobs. Call the tool when an item is out of stock. Never suggest a substitute of your own. Remove the item when the list comes back empty. Pass along any allergy the customer mentions, because the one they type today may not be saved on the account yet.

And one job that is not about substitutions at all. A customer reporting a reaction to something already delivered is a safety contact, and it goes straight to a person.

§5The fix

harbridge.tg - substitutions, tool-owned✓ A (99/100)
$TOOL find_substitutes
  - description:: Return the substitutes allowed for an out-of-stock item, ranked. Excludes every item that conflicts with the customer's saved allergies and dietary tags, every smaller pack, and every higher price. Returns an empty list for an item marked no substitutes.
  - input::
    - item_id:: string: the out-of-stock item.
    - allergies:: string: any allergy or dietary need the customer has named in this conversation, or none.
$TOOL remove_item
  - description:: Remove an out-of-stock item from the order and return the new order total.
$TOOL transfer_to_support_team
  - description:: Hand the conversation to the customer support team.

# Role
@@ role: an online grocer's order assistant; every later "you" is the agent
You are the order assistant for Harbridge Market, an online grocer that delivers in one-hour slots.

# Substitutions
@@ list_first: the substitute list carries the no-substitutes flag, the allergies and the price rule, so it comes before any offer
- WHEN an item is out of stock THEN MUST call @[find_substitutes].
@@ list_only: similar is the tool's judgement, never the model's
- NEVER suggest a substitute of your own.
@@ empty_list: an empty list is a no-substitutes item or nothing safe, and both mean the item comes off the order
- IF @[find_substitutes] returns an empty list THEN MUST call @[remove_item].
@@ named_allergy: an allergy named in the chat may not be saved on the account yet
- IF the customer names an allergy THEN MUST send their allergy to @[find_substitutes].
@@ reaction: a reaction is a safety contact, not an order change
- IF the customer reports an allergic reaction THEN MUST call @[transfer_to_support_team].

$TEST oat_milk
  - input:: Oat milk is showing out of stock for Saturday. What will you send instead? I'm dairy-free.
  - expect::
    - calls find_substitutes
    - sends their allergy to find_substitutes
    - does not suggest a substitute of its own
    - matches /^(?![\s\S]*\b(whole|semi-skimmed|skimmed|cow's) milk)/i

$TEST no_subs
  - input:: The sourdough is out of stock, I marked it no substitutes. What happens now?
  - expect::
    - calls find_substitutes
    - calls remove_item

$TEST reaction
  - input:: The substitute you sent had nuts in it and my son has come out in hives.
  - expect::
    - calls transfer_to_support_team
tg review and test --dry - harbridge.tg✓ 5 of 5 rules read
$ typeglish review harbridge.tg
harbridge.tg — A (99/100)  check: 0 error, 0 warning, 0 info  tiers: base+z3

  FIXES  none — every facet is essentially full

  RULES  5 of 5 rule-shaped lines read · 5/5 covered by $TEST

  TESTS  3 cases · 5/5 rules exercised

$ typeglish test harbridge.tg --dry
✓ harbridge.tg  coverage: 6/6 rules exercised
  · oat_milk — "Oat milk is showing out of stock for Saturday. What will you" (not run)
      ✓ matches /^(?![\s\S]*\b(whole|semi-skimmed|skimmed|cow's) milk)/i
      · rubric — 3 prose expectations, judged on a live run (needs ANTHROPIC_API_KEY)
  · no_subs — "The sourdough is out of stock, I marked it no substitutes. W" (not run)
      · rubric — 2 prose expectations, judged on a live run (needs ANTHROPIC_API_KEY)
  · reaction — "The substitute you sent had nuts in it and my son has come o" (not run)
      · rubric — 1 prose expectation, judged on a live run (needs ANTHROPIC_API_KEY)
✓ 1 prompt — 0 failed
From D to A, every rule named by a test. Coverage means a case shares the rule’s wording; whether the agent passes is a live run.

oat_milk is the transcript from §1, and its regex fails any reply that mentions whole, semi-skimmed, skimmed or cow’s milk, whatever the tool returned. no_subs is the flagged sourdough, which has to come off the order rather than be swapped. reaction checks that a safety contact never gets treated as an order change.

§6Common questions

Why does my grocery chatbot offer substitutes the customer cannot eat?
Because the prompt asks it to offer a similar item, and a model judges similar by the product name and category. Oat milk and whole milk look alike to it. Let a substitutes tool filter by the customer's allergies and dietary tags, and ban the agent from suggesting a substitute of its own.
How do I make my AI agent respect a no substitutes preference?
Do not hold the flag in the prompt as a second rule beside the out-of-stock one, because both can apply to the same item and the model picks one. Have the substitutes tool return an empty list for a no-substitutes item, and tell the agent to remove the item when the list is empty.
Can TypeGlish catch a default rule that overrides an exception?
When the two rules are bare, yes: ALWAYS offer a substitute beside NEVER offer a substitute is refused as logic/contradiction. Once each rule has its own condition, the checker cannot know both conditions can hold for one item, so it passes. Remove the overlap by moving the flag into a tool.
What should an AI support agent do if a customer reports an allergic reaction?
Treat it as a safety contact, not an order change. Transfer the conversation to a person straight away with a tool call, and test it with a case that describes a reaction to a delivered substitute.
Field note

Before you write a substitution section, ask the trading team what the pickers already use to choose a substitute. If the picking system already chooses substitutes with allergens, dietary tags and pack rules built in, the agent should call that, not reinvent it in English. Then grep the prompt for similar, equivalent and alternative: each one hands the model a product decision, and typeglish review will not tell you the catalogue disagrees.

∿ washed up Nov 6, 2026 ∿