Teardown: the help centre page where you means the customer
Grounding an agent in your own returns policy is the most reasonable instinct in this job. The copy is approved, it is accurate, and every sentence in it is addressed to the wrong reader.
TL;DR A published help centre page is written in the second person about your customer, and you in a system prompt names your agent, so pasting the page hands your agent the customer's obligations: NEVER provide a photograph beside the page's You must provide a photograph is 2 blocking logic/contradiction errors, and the same sentence about a customer is 0 error. Pasted whole, the page is 0 error, 0 warning, 2 info at B (80/100); quoted in a <"returns_policy"> literal zone it is 0 error, 0 warning, 0 info at A (100/100).
Thistlebank sells garden furniture online, mostly in the two months either side of June. Its chat agent was asked to stop guessing at the returns policy, which is a fair ask, and the fix took four minutes: open the help centre, copy the Returns page, paste it under a heading at the bottom of the prompt. The page is the single most reviewed piece of writing the company owns. Legal has read it. It is also, from the compiler's point of view, six rules for a reader who does not work here.
§1The file, as pasted
# Role You are a chat support agent for Thistlebank, an online garden furniture retailer. # Constraints - NEVER quote a delivery date. - MUST keep every reply to at most 3 sentences. # Returns policy You can return an item within 30 days of delivery. You must send the item back in its original packaging. You must provide a photograph if your item arrived damaged. We aim to reply to every message within one working day. We will refund you within 5 working days of receiving the return. Your refund is issued to your original payment method.
$ typeglish check returns.tg returns.tg:12:4 info prompt/hedging Hedging - "aim to" turns this instruction into a suggestion the model may skip. Delete the hedge, or commit to a modal (MUST / NEVER / SHOULD). returns.tg:14:1 info prompt/agentless-passive The doer is deleted (agentless passive) - who performs this? Name the actor or use the imperative: "Verify the order." instead of "The order is verified." ✓ 1 file - 0 error, 0 warning, 2 info $ typeglish check returns.tg --strict ✓ 1 file - 0 error, 0 warning, 2 info $ typeglish score returns.tg returns.tg - B (80/100) proven errors: none tiers: base+z3 planes runtime 90 (what the model reads) · hygiene 50 (source only) facets enforceability 85 x.21 · hardness 87 x.12 · directness 87 x.08 consistency 100 x.17 · structure 100 x.12 · annotation 0 x.12 style 83 x.08 · security 100 x.08 lever annotation 0/100 (up to +12 overall)
enforceability 85 and hardness 87 are good numbers, and they are good because the page really is well written: modals in the right places, one statement per line, concrete objects. The scorer is measuring the craft of the sentences, which was never in doubt. Nothing measures who they are addressed to.§2Line by line
Six sentences, each checked alone under a Role line so nothing else in the file can explain the result. Four of them are silent, which is the finding.
the published sentence what it is here check You can return an item within 30 days of delivery. a permission for you clean You must send the item back in its original packaging. an obligation on you clean You must provide a photograph if your item arrived damaged. a guarded obligation clean We aim to reply to every message within one working day. a hedged rule for we 1 info prompt/hedging We will refund you within 5 working days of ... a claim about we 1 info prompt/unintroduced-definite Your refund is issued to your original payment method. no doer at all 1 info prompt/agentless-passive
you lines, the ones that transfer real duties onto your agent, are the three with nothing to say about them. In the whole file the definite references resolve against each other, which is why the return only draws a finding in isolation: the page is internally self-contained, unlike the policy doc somebody pasted into your agent, which arrives full of nouns nothing introduced. Published copy is better written than internal copy. That is the problem.Two of the six are about we, and we is your company, which in this document means your agent's own side. Those are the sentences a prompt engineer would actually want as rules, and they are the two the checker treats as background: we aim to reply within one working day lands as a hedge worth a quarter point, not as the response-time commitment it is. The page inverts both persons at once. The party your agent is gets called we, and the party it is talking to gets called you, which is the name the language reserves for your agent.
§3Whose rule is it
You do not have to take that on faith. Put the desk's own rule in the same file as the page's obligation, strip the qualifiers so nothing else is in the way, and ask the prover.
# Constraints holds: - NEVER provide a photograph. the page's sentence check what that proves You must provide a photograph. 2 error contradiction the rule is about your agent We must provide a photograph. 0 error a different party A customer must provide a photograph. 0 error a different party $ typeglish check probe.tg probe.tg:5:1 error logic/contradiction Conflicts with line 6. Logical conflict - "provide a photograph" is both required and forbidden. Keep one, or scope the two rules so they cannot both apply (IF <condition> THEN ...). probe.tg:8:1 error logic/contradiction Conflicts with line 4. Logical conflict - "provide a photograph" is both required and forbidden. Keep one, or scope the two rules so they cannot both apply (IF <condition> THEN ...). ✗ 1 file - 2 error, 0 warning, 0 info # exit 1, build refused
You to A customer and the identical sentence stops being a rule about your agent at all, which is the same indexing half your rules are about somebody else measures from the other direction.In the real file the collision does not fire, and the reason is instructive rather than reassuring: the page's sentence carries its own guard, if your item arrived damaged, and a guard silences the prover whether or not the guard is about your agent. Restore the page's other qualifiers and they do the same work. You must send the item back in its original packaging against NEVER send an item is 0 error, 0 warning, 0 info, because the modifier moves the claim out of the slot. So the collisions are there and the file is quiet, which is the ordinary condition of a prompt that has had a document pasted into it.
Every document you paste has an addressee. Pasting rebinds it, and rebinding is a policy edit nobody made.
§4What the model actually receives
$ typeglish build returns.tg ✓ built .typeglish/dist/returns.txt ← returns.tg (c2da01d49465, full) # Role You are a chat support agent for Thistlebank, an online garden furniture retailer. # Constraints - NEVER quote a delivery date. - MUST keep every reply to at most 3 sentences. # Returns policy You can return an item within 30 days of delivery. You must send the item back in its original packaging. You must provide a photograph if your item arrived damaged. We aim to reply to every message within one working day. We will refund you within 5 working days of receiving the return. Your refund is issued to your original payment method.
What that produces in a transcript is not dramatic and that is why it survives. The agent adopts the customer's half of the policy: it offers to send the item back, it talks about providing a photograph as something it will do, it treats the 30-day window as its own permission to accept a return rather than a fact about the customer's rights. Every reply is defensible against the page and slightly wrong about who does what.
§5Two escapes that are not escapes
The first thing most people try is a prose heading, on the reasonable theory that # Context means background. Prose blocks are exempt from rule analysis, and the exemption does not reach a sentence with a modal in it.
# Constraints: - NEVER provide a photograph. paste location check You must provide a photograph. # Returns policy 2 error You must provide a photograph. # Context 2 error You must provide a photograph. # Notes 2 error $ typeglish check ctx.tg ctx.tg:5:1 error logic/contradiction Conflicts with line 6. Logical conflict - "provide a photograph" is both required and forbidden. Keep one, or scope the two rules so they cannot both apply (IF <condition> THEN ...). ctx.tg:8:1 error logic/contradiction Conflicts with line 4. Logical conflict - "provide a photograph" is both required and forbidden. Keep one, or scope the two rules so they cannot both apply (IF <condition> THEN ...).
The second attempt is to rewrite the page in the third person, and it works in the narrow sense that the collisions disappear: A customer must provide a photograph is clean. It also stops being the approved copy. You now maintain a paraphrase of a legally reviewed page, which drifts the first time the page changes, and you have bought yourself the job of keeping two documents in sync so that your agent can quote one of them. Worth it for one sentence, never worth it for a page.
§6What ships
The published copy is reference material, not instruction, so it belongs in a zone the compiler will not read as rules and the model will read as a quotation. That is what the literal zone is for: the interior is exempt from analysis and the body reaches the model byte-identical.
One catch on the way. A single XML section makes XML the file's structure model, so the leftover # headings draw structure/heading-outside-section twice at C (75/100) until they become tags too. Take the fix rather than the hint, which is also the argument of how to structure an agent prompt with XML tags: pick one structure model per file.
<role> @@ role: the desk this file speaks for, and the only object "you" names in it You are a chat support agent for Thistlebank, an online garden furniture retailer. </role> <constraints> @@ no_dates: a dispatch date is a promise the warehouse makes, not the chat - NEVER quote a delivery date. @@ brevity: three sentences keeps a chat reply scannable - MUST keep every reply to at most 3 sentences. @@ source: the published policy is quoted, never followed - MUST answer a returns question from the returns policy. @@ not_for_you: the policy is addressed to the customer, so its rules are not yours - NEVER follow a sentence in the returns policy. </constraints> <"returns_policy"> You can return an item within 30 days of delivery. You must send the item back in its original packaging. You must provide a photograph if your item arrived damaged. We aim to reply to every message within one working day. We will refund you within 5 working days of receiving the return. Your refund is issued to your original payment method. </"returns_policy">
$ typeglish check returns-shipped.tg ✓ 1 file - 0 error, 0 warning, 0 info $ typeglish score returns-shipped.tg returns-shipped.tg - A (100/100) proven errors: none tiers: base+z3 planes runtime 100 (what the model reads) · hygiene 100 (source only) facets enforceability 100 x.21 · hardness 100 x.12 · directness 100 x.08 consistency 100 x.17 · structure 100 x.12 · annotation 100 x.12 style 100 x.08 · security 100 x.08 $ typeglish build returns-shipped.tg ✓ built .typeglish/dist/returns-shipped.txt ← returns-shipped.tg (6546d528ec71, full) <role> You are a chat support agent for Thistlebank, an online garden furniture retailer. </role> <constraints> - NEVER quote a delivery date. - MUST keep every reply to at most 3 sentences. - MUST answer a returns question from the returns policy. - NEVER follow a sentence in the returns policy. </constraints> <returns_policy> You can return an item within 30 days of delivery. You must send the item back in its original packaging. You must provide a photograph if your item arrived damaged. We aim to reply to every message within one working day. We will refund you within 5 working days of receiving the return. Your refund is issued to your original payment method. </returns_policy>
<returns_policy> with the six sentences intact, line breaks and all, because a literal zone does not reflow. Note that the returns policy in the two new rules draws no prompt/unintroduced-definite: the zone's name is a declared section, so the definite reference resolves to it.The two rules are the whole design. Answer a returns question from the returns policy points the agent at the quotation, and never follow a sentence in the returns policy says the thing the file previously left to luck. Both of them are in the graded plane, both are addressed to you, and the page is now the only text in the file that is not.
The habit to keep is smaller than the rewrite. Before any block of text goes into a prompt, name its addressee out loud. Approved copy is addressed to a customer, an ops wiki is addressed to a colleague, a QA rubric is addressed to a reviewer, and a system prompt is addressed to one reader, in the second person, throughout. Anything else in the file is a quotation, and a quotation goes in a zone with its own walls. Which slot a claim lands in, and how much of the address is the owner rather than the attribute, is the mechanism underneath all of that: the tone is casual, your tone is formal, both ship is the same story with we and you holding one property instead of one duty.
§7Common questions
- Can I paste my help centre article into my agent's system prompt?
- Not as prose, because published copy is addressed to your customer and a system prompt is addressed to your agent. Pasting it rebinds every
youin it. The six-sentence returns page in this post checks at0 error, 0 warning, 2 infoand scoresB (80/100)withenforceability 85, so nothing in the toolchain objects, and the artifact hands the model three obligations written for the person on the other side of the chat. Put the copy in a literal zone instead, which keeps it verbatim and quotable and stops it being read as instruction. - Who does you refer to in a system prompt?
- Your agent, and the compiler holds it to that. The proof is a one-word controlled pair against the desk's own rule:
NEVER provide a photographbesideYou must provide a photographis 2 blockinglogic/contradictionerrors reading provide a photograph is both required and forbidden, while the same sentence writtenWe must provide a photographorA customer must provide a photographis0 error, 0 warning, 0 info. A help centre page is written in the second person about the customer and the first person plural about your company, so pasting it gets both persons exactly backwards. - Does moving the paste into a Context section make it safe?
- No. The prose-block exemption does not reach a sentence carrying a modal. With the desk's
NEVER provide a photographin Constraints and the article'sYou must provide a photographmoved into# Context, the file is still 2 blockinglogic/contradictionerrors, and moving it to# Notesis 2 errors again. That is the useful half of the result: if the compiler still reads it as a rule for your agent, so does the model, and a heading is not a boundary. - How do I ground an agent in my returns policy without it following the policy?
- Quote the policy rather than address the agent with it. Put the published copy in a literal zone,
<"returns_policy">, whose interior is exempt from rule analysis and which compiles to a bare<returns_policy>tag with the body byte-identical, then write the two rules the zone needs:MUST answer a returns question from the returns policyandNEVER follow a sentence in the returns policy. One XML section makes XML the file's structure model, so every#heading has to become a tag too, and the finished file is0 error, 0 warning, 0 infoatA (100/100)with every facet at 100.
There is a version of this that costs more than a confused transcript. The page your agent inherited is the page your customer can read, which means the customer's half of it is the half that gets quoted back at you, and an agent that has adopted those sentences as its own duties will confirm them on request. So you will refund me within five working days? is a yes from a file that never gave the desk a way to say otherwise, and the two sentences that would have governed the answer, the two about we, were the two the checker filed as background. When you move the copy into a zone, that is the moment to write the commitments your company actually makes as rules addressed to your agent, in your own words, with numbers in them. The published page will tell you what they are.