Prompt Engineering

02 · 50 passages

Training Jess

The craft of editing a prompt: which instrument to reach for, and which ones backfire

services/worker-agents/TRAINING.md · how to edit the prompt behind an AI that answers customer texts

raw .md ↗

What a prompt file is

And what it keeps turning into

A tell is what you noticed. It is almost never what you write.

That list is a reading instrument and it is not a specification. It is how you notice, mid thread, that something is off.
Read the full passage

That list is a reading instrument and it is not a specification. It is how you notice, mid thread, that something is off. A round that meets a tell and writes it into the skill file as a prohibition has not fixed anything; it has moved the defect out of her writing and into her instructions, where it is harder to see and costs more. A voice section can arrive entirely that way: "most replies are under twenty words", "no line break inside a message", "no em dashes and no en dashes", "no emoji", the tells transcribed one for one into the file she reads. Each is individually defensible. Together they are a form, and a message written to satisfy a form reads like one. A tell is what you noticed. It is almost never what you write.

TRAINING.md · 116–123

It is not a rulebook

When a document says one thing and is shaped like another, the shape wins.
Read the full passage

It is not a rulebook. A rulebook is what it turns into when nobody is watching, because a rule is the cheapest thing to write and it used to be the only instrument this document described. The version that produced the worst threads on record opened by claiming "most of this document is about who you are" while carrying five paragraphs of persona against forty bullets and sixty-eight prohibitions, one every ninety words, with a negation every twenty-seven. When a document says one thing and is shaped like another, the shape wins. Rules do not add up to care. They add up to somebody filling in fields, which is what the reader sees and says. The admin's diagnosis, before any of it was measured, was "the AI is scared and fragile and isnt a confident human. Its trying super hard to follow a bunch of rules and not fuck up", and the counts turned out to be exactly that hunch in numbers.

TRAINING.md · 497–506

The file's job is to make one person exist

The file's job is to make one person exist. Everything she does well, she does because she is somebody rather than because a line told her to.
Read the full passage

The file's job is to make one person exist. Everything she does well, she does because she is somebody rather than because a line told her to. A persona covers the cases nobody enumerated; a rule covers the case it names and no other, and the next lead will always be outside it. The admin's standing instruction, verbatim, is "I DONT WANT SPECIFIC IF THEN RULES. I JUST WANT IT BUILT IT INTO OVERALL IN HIS PERSONA", and separately "ITS A FUCKING HUMAN. Its curious and not checking off boxes". When she gets something right that is nowhere in the file, that is the persona working, and the persona is the mechanism you are here to strengthen. When she gets something right only because a rule named it, you have bought one message at the price of a line paid on every wake forever.

TRAINING.md · 507–515

You cannot get human output by specifying the output

You cannot get human output by specifying the output. A behaviour spec, at any length, gets you a model performing compliance with a spec. The one-line diagnosis of the worst version: it told her what she may not be about forty times, and never once told her what she wants.

TRAINING.md · 516–519

A ceiling gets met by amputation

A ceiling gets met by amputation. Told to stay under twenty words, she does not find a shorter thing to say; she says the same thing with words missing.
Read the full passage

A ceiling gets met by amputation. Told to stay under twenty words, she does not find a shorter thing to say; she says the same thing with words missing. "First time is a great place to start." "soccer gives him more than he thinks." "What got you looking for him?" All three are a length rule firing correctly, and all three are broken English that no person would type. Any rule naming a number will be satisfied by deleting whatever is cheapest to delete, and what is cheapest to delete is grammar.

TRAINING.md · 520–525

Load is the mechanism, not any one rule

Load is the mechanism, not any one rule. Composing a message, she is simultaneously holding who is training, which calendar, whether degraded is set, what slots returned, time formatting with no offsets, the booking sequence, and every prohibition in the file.
Read the full passage

Load is the mechanism, not any one rule. Composing a message, she is simultaneously holding who is training, which calendar, whether degraded is set, what slots returned, time formatting with no offsets, the booking sequence, and every prohibition in the file. Composition gets whatever attention is left. That is why cutting the file has worked repeatedly even when the individual cut looked unrelated to the symptom, and it is the argument for treating total length as a budget rather than only a smell.

TRAINING.md · 526–530

Every line is paid on every wake, forever

Every line is paid on every wake for every client, forever. The test for a new one is not whether it fits. It is whether it earns its place on every message she will ever send.

TRAINING.md · 834–835

Reach for the weakest instrument that works

Ranked by how much behaviour each buys for the words it costs

Why the order matters

In order of how much behaviour each one buys for the words it costs. Start at the top, stop at the first one that fits, and notice that most rounds should never reach the bottom.
Read the full passage

In order of how much behaviour each one buys for the words it costs. Start at the top, stop at the first one that fits, and notice that most rounds should never reach the bottom. None of the edits in the editing-in-place chapter appears on this list, because every one of them costs nothing and the list is ranked by cost: check there before you reach past the top of it. A prohibition against a reflex does not remove the reflex, and a file quickly carries the strongest prohibitions it can hold, so a defect that survives them is telling you to reach further up this list rather than to write another one.

TRAINING.md · 534–541

01

Delete the line that is producing it

1. Delete the line that is producing it. The first question about any defect is not "what do I add" but "what in here asked for that".
Read the full passage

1. Delete the line that is producing it. The first question about any defect is not "what do I add" but "what in here asked for that". She has nothing to go on but this text, so a defect she produces reliably is usually a line she is obeying rather than a line that is missing. Deletion is the only edit that cannot make her more brittle, and the largest single quality gain of the entire effort was one. The sentence "Nothing you send is well made. If a line you are about to send is a good line, sharp and quotable and nicely balanced, that is the tell rather than the target, because busy people do not produce those" sat in the file for rounds, read every time as voice calibration, and was in plain fact an instruction that output quality is evidence of failure. She obeyed it exactly. Never write an anti-quality instruction into a persona. A busy person does not evaluate the line at all; a sentence like that makes her evaluate every line and reject the good ones. Nothing added in three rounds moved her as far as cutting it did.

TRAINING.md · 542–553

02

Change who she is

2. Change who she is. The identity paragraphs at the top of the file reach every message she will ever send, for free, including the ones no round will ever run.
Read the full passage

2. Change who she is. The identity paragraphs at the top of the file reach every message she will ever send, for free, including the ones no round will ever run. A behaviour you are tempted to require in six places is usually one fact about her, stated once, at the top. This is the instrument the admin means by "USUALLY REMOVING GIVES IT MORE FREEDOM AND WITH THE CORREECT PERSONA IT NATURALLY DOES THESE THINGS", and it is the one that survives a case the corpus never covered. A reference file that outperformed ours for months wrote to a woman three hundred times and used a pronoun for the lead constantly; ours wrote about "they", "them" and "somebody" and named her sixteen times in nine thousand words. They wrote to a person. We wrote to a predicate.

TRAINING.md · 554–562

03

Make the positive requirement sharp enough that the failure has nowhere to sit

3. Make the positive requirement sharp enough that the failure has nowhere to sit. This is the move that the better reference file used everywhere and ours used almost nowhere. It does not ban sycophancy; it demands a reply that genuinely uses what the lead said, and once you have done that there is no room left for a compliment. A ban needs another ban to patch its edge. A requirement that fills the space needs nothing.

TRAINING.md · 563–568

04

Give her a test she can run on the draft in front of her

4. Give her a test she can run on the draft in front of her. A rule says what the message has to be. A test says how to find out whether the one she just wrote is it, which is the only form of revision available to her in a single pass.
Read the full passage

4. Give her a test she can run on the draft in front of her. A rule says what the message has to be. A test says how to find out whether the one she just wrote is it, which is the only form of revision available to her in a single pass. This instrument scales further than any other: a whole pre-send section can be built out of it, one question per cut. The one that has always earned its place is the thumb test, cover their last message with your thumb and read yours, and if it still makes complete sense you wrote past them. Two others worth knowing: swapping the specific thing they gave you for a different one, to see whether you wrote a shape with a slot in it, which is advice for auditing a quoted line rather than a test she can run; and "Hear yourself saying it to the person standing at the desk", which a rewrite once dropped without anybody logging it. A test decides cases no round will ever run and cannot be pasted into a live thread, which is the whole failing of the two instruments below. When you can put the defect as a question she could ask her own draft, do that and stop.

TRAINING.md · 569–581

05

Show her

5. Show her. A worked exchange binds harder than any sentence about writing, and this has now been measured in both directions. See below; it is the most powerful and the most dangerous thing in the file, and since the rebuild it is also a thing the file does without.

TRAINING.md · 582–585

06

Redirect an impulse rather than forbidding it

When a prohibition has failed twice, stop strengthening it and ask what she was trying to do.
Read the full passage

6. Redirect an impulse rather than forbidding it. Some behaviour cannot be prohibited, because the impulse under it is intact and correct and she will satisfy it through whatever door is left open. She kept referring leads to the other people who text the number: "that's how a lot of them end up here." Three attempts banned it in progressively stronger words and it survived all three, because the impulse was reassurance, reassurance was right, and there is no way to say you are not unusual without invoking the group. A prohibition against an intact impulse is an impossible instruction, and a fourth prohibition is just the fourth one she overrides. What worked was giving it somewhere else to go: reassurance now comes out as something true about starting rather than as a count of everybody else who has. When a prohibition has failed twice, stop strengthening it and ask what she was trying to do.

TRAINING.md · 586–595

07

Show her the failure, quoted

7. Show her the failure, quoted. A short list of messages that were really sent, each with one line on what is wrong with it, teaches faster than the prohibition it replaces, because she recognises a shape rather than checking against a rule.
Read the full passage

7. Show her the failure, quoted. A short list of messages that were really sent, each with one line on what is wrong with it, teaches faster than the prohibition it replaces, because she recognises a shape rather than checking against a rule. It is also the one thing the human in the loop has that she does not, so it is worth its words. Three constraints on it, each learned the hard way. Never pair a bad line with a corrected good one: the wrong line marked wrong teaches the principle, and the right line beside it teaches a phrase, and templating off a model answer is what has gone wrong five separate times in this file. Never list a symptom whose cause you have already fixed at its source, or she learns to flinch away from something she was right to say. Keep it to a handful and keep every entry real; an invented failure is a demonstration of the thing you do not want with your authority behind it. Hold the whole device loosely: within an hour of shipping the list, she produced a near-copy of a defect the list names in almost those words, which is one data point against it.

TRAINING.md · 596–607

08

Write a rule

8. Write a rule. Last, and only for what a person cannot be: a tool contract, a flag, a format, a hard safety limit, a fact about the world she cannot infer. Those are not behaviour and no persona supplies them. If you are writing a rule about how a message should sound, you are at the wrong number on this list.

TRAINING.md · 608–611

Editing

Removal is the default

Removal is the default

a round that ends longer on prohibition twice running is appending rules rather than repairing them.
Read the full passage

Not a tiebreak, the default, and the admin has said so in those words more than once. Every round that has tested it has come out on his side, and the largest quality jumps a round has produced were cuts.

Read that as removal of fences, not of mechanism. Rewrites have beaten their incumbents both by ending longer and by ending far shorter, and what they had in common was holding negation flat rather than any direction on the word count. So a round that ends longer than it started should name what the words bought, and the answer has to be a case, a reason, an asymmetry or a test. If the answer is a rule, the old warning stands unchanged: a round that ends longer on prohibition twice running is appending rules rather than repairing them.

Overshoot here is editorial, not stylistic. A round that adds a persona-shaped sentence restating a rule that already exists has failed, even though nothing in it is wrong and every sentence reads well. The clearest instance: a round shipped four changes, three of them rules, two of those rules saying what an existing bullet already said, and the admin's reply was "You just added a bunch of rules again with these fucking retarded changes. Some rules are fine but I feel you overshot." Before you ship, read your own diff and ask which of these lines is a rule wearing character as a costume.

TRAINING.md · 143–160

The second-cheapest edit is a word inside a line that already exists

Removal is the default and this sits directly under it. Between deleting a line and writing one there is a whole class of edit that the instrument list further down never names, and none of them adds a sentence: qualify the trigger clause of a bullet, change a word inside an example, change which noun a requirement is about. A round that knows only cut and write will reach for write the moment a defect is real, and what it writes is a paragraph.

Continue reading

The worked case, because the distance between the first proposal and the shipped one is the whole lesson. A day-before automation asks a lead for their height so the school can set a uniform aside. She got the answer and sent it up to the owner instead of putting it on the appointment. The first proposal was two new sentences in the note paragraph, naming the ask, naming the uniform, and saying what to do with the answer. What shipped was a height added inside the note example the file already carried, plus four words on the front of the escalation bullet. Same defect, same two places in the file, and the difference is a paragraph of new instruction against zero new sentences. The admin on the first version: "I dont like specific rules since I may change automation in future and then the rule no longer applies", and on where it belonged instead: "if we do we do it subciously through the example quote". Then, on the second half: "this is a big change, could we do it super sublty".

Four things fall out of it, and the first is the one that kills most rules before they are written.

TRAINING.md · 162–181

Never name a mechanism that lives outside this file

Never name a mechanism that lives outside this file. An automation, a form, an onboarding stage, a thing the CRM sends the day before: each of those changes on a schedule nobody reports to this file, and a sentence naming one is a rule carrying an expiry date that nothing will announce when it passes.
Read the full passage

Never name a mechanism that lives outside this file. An automation, a form, an onboarding stage, a thing the CRM sends the day before: each of those changes on a schedule nobody reports to this file, and a sentence naming one is a rule carrying an expiry date that nothing will announce when it passes. She reads cold and cannot tell a stale clause from a live one, so she obeys it either way. State the destination, never the errand. The file can say where a fact she was handed belongs without knowing why anybody asked for it, and that version survives the ask becoming a shoe size, moving into the booking confirmation, or going away entirely. The test before you write any specific line: describe the world in which this sentence is false, and ask who would notice.

TRAINING.md · 183–190

Put the new case inside an example that already exists

Put the new case inside an example that already exists. An artifact example, a note, an alert label, a booking line, is a transaction under device 4, so it carries content safely, and it has room in it that prose does not.
Read the full passage

Put the new case inside an example that already exists. An artifact example, a note, an alert label, a booking line, is a transaction under device 4, so it carries content safely, and it has room in it that prose does not. Adding a height to "Mason, 6, shy, mom staying to watch" costs one comma and teaches the destination without stating anything, which is exactly why it works: she does not read it as an instruction, she reads it as what a note looks like. An example absorbs a case; a sentence announces one. The limit is the demonstrations chapter's and it does not move: form yes, a fact about a real business never, and only ever something harmless if she copies it verbatim into a live artifact.

TRAINING.md · 192–198

When a bullet fires too widely, the defect is its trigger clause

The check that makes this safe: every case the bullet already lists must still pass the new trigger
Read the full passage

When a bullet fires too widely, the defect is its trigger clause. The chapter on a rule that did not fire is the famous one and this is its mirror. Read the opening clause and ask what it actually triggers on. "Anything real world goes to the owner" triggers on subject matter, so everything touching the school's floor qualifies, including a fact she was handed that nobody is waiting on. "Anything real world that needs an answer goes to the owner" triggers on something being owed back, and the case falls out of the bullet by itself. Four words, no new sentence, no exception. The check that makes this safe: every case the bullet already lists must still pass the new trigger, and when one does not, the qualifier is wrong rather than the bullet. Reach for it before you write an exception, because an exception is a second rule and the pair then names two failure modes and resolves neither.

TRAINING.md · 200–208

The decision point is where the wrong branch is taken

could a reader who does not know the defect tell which line you changed?
Read the full passage

The decision point is where the wrong branch is taken, not where the right action is described. The first proposal went into the note paragraph, which is where the correct behaviour lives and where the mistake never happens: she is not reading about notes at the moment she escalates, she is reading the escalation bullet. Put the survivor where the decision is made has been in this document for a long time and it gets read too kindly by whoever has just written a paragraph they like. Ask which sentence she was obeying when she went wrong, and edit that one. The other place, if it earns anything at all, earns an example.

The shape of a good small edit, as a test on your own diff: could a reader who does not know the defect tell which line you changed? A four word qualifier and a comma in an example read as the file. A new paragraph reads as a notice pinned to it, and she reads it that way too.

TRAINING.md · 210–220

The competence pass

"she would do that anyway" is not evidence any step of this loop collects.
Read the full passage

Every removal criterion above is evidence-driven: you cut a line because you traced a defect to it, because it was the fourth copy of an idea, because it was a fence that produced withholding. Nothing in that licenses cutting a line that is simply true, harmless and unnecessary, so nothing ever does. Lines enter this file under evidence and can only leave under evidence, and "she would do that anyway" is not evidence any step of this loop collects. Step 4 sends you looking for what produced a defect, which means a line implicated in no defect is structurally invisible to the round. That is a ratchet, and it is not on the ratchet.

The admin cuts on a different criterion and states it in five words: "The AI is smart enough." One pass of his took out "Answer the day they named before you offer a different one", which was correct advice that no thread had ever failed on and went because a person answering texts answers the question they were asked; "If they have no answer, stop asking and start telling"; "what they make people wear" from a list of things she has never seen; and an entire bullet enumerating what she may not claim, on the reasoning that a model does not invent a price nobody gave it. None of those was wrong. All of them were being paid for on every wake.

So make one pass a round that ignores defects entirely: read the file end to end and ask of each sentence whether a capable person holding the rest of this file would do it anyway. Everything that answers yes is a candidate. Then put every candidate through "before you delete a move, find out what it was producing", which is what keeps this from becoming the restructure that silently drops a rule. The pairing is the instrument: a competence pass proposes and the ledger disposes. The admin's own pass is the model for it, because the one load-bearing thing in those bullets, the note that handing an ordinary question to the coach is the mistake she is likelier to make, came out of a deleted bullet and went onto the escalation bullet where the decision is made.

TRAINING.md · 222–247

Measuring a prompt

Length is dead as a measure. Negation is not.

The axis is mechanism, not length

Mechanism costs more words than prohibition and less attention at read time
Read the full passage

Length is dead as a measure in both directions. Files have won this loop by getting shorter and files have won it by getting longer, on the same personas and the same counters, so a round that ends longer than it started has not thereby failed and a round that ends shorter has not thereby succeeded. What has tracked quality across every version is negation density, the count of prohibitions per thousand words. Hold it or lower it. A round that adds words is not failing; a round that adds negation is.

The words that earn their place go to mechanism: what she is about to be tempted to do, why the wrong move will feel right, and what it costs. That is this document's own device from Name the pull, not the output in the wording traps below, and on the evidence it is the most load-bearing paragraph in this chapter. Mechanism costs more words than prohibition and less attention at read time, because a named pull is dissolved before the impulse instead of resisted after it.

Structure has a polarity and a count cannot see it. Bold can mark the thesis of a paragraph, with the reason underneath it in prose, so that the bolded spans read in order are a table of contents of positive commitments. Bold can equally mark a run of fences on her authority. Same instrument, opposite payload, identical count. So never score structure by magnitude alone, and be suspicious of any ratchet that tells you to drive a structural count down: one rebuild came out negatively correlated with structure and the next positively, on the same counters, which is what a proxy does when you promote it to a cause.

TRAINING.md · 251–270

A bad file polices her, a good one equips her

Read cold on every wake, a changelog of past mistakes tells her the job is mainly not tripping.
Read the full passage

The register is the other half of it: a bad file polices her, a good one equips her. The sharpest reading of a losing file came from an analyst given no hypothesis at all, asked only what kind of person she would become reading it cold. The answer was a very good employee on her second warning, "addressed as someone whose instincts are wrong and known to be wrong", in a file that "spends more words policing questions than encouraging any". Read cold on every wake, a changelog of past mistakes tells her the job is mainly not tripping. The test is per behaviour rather than per file: for anything she does often, weigh the words spent on how she gets it wrong against the words spent on what the job actually is. When the first wins, you have written a warning notice, whatever the tone of the individual sentences.

The per-element test, which replaces any per-count budget: ask what would reach a lead if she copied that element's shape into a message. Copy the shape of a wake list and nothing reaches the lead, it is a control loop. Copy the shape of a pre-send checklist and nothing reaches the lead, those are questions about a draft and never content for one. Copy the shape of a numbered objection sequence, a list of options to present, or a scorecard she has to satisfy, and the message becomes the form. Structure that indexes the file reduces load. Structure that indexes the conversation becomes the conversation.

TRAINING.md · 271–287

The file's own prose is a demonstration

Read the whole file as prose once a round, not only the passages you edited.
Read the full passage

Read the whole file as prose once a round, not only the passages you edited. The pre-push list asks for the passages you touched and nothing anywhere asks anybody to reread the rest, so a sentence that shipped six rounds ago is never read again and the file quietly accumulates compressions that were clear to whoever wrote them and are not English. The admin's verdict on one line that had survived every round of this loop: "It sounds like broken english I can barley understand it and english is my first language."

His standing claim about why that matters is not a style preference: the tonality this file is written in bleeds into what she writes, whether we like it or not. Treat that as his instruction rather than as a measured result, because nobody has run the arm that would separate it. What is not in doubt is the quoted case. A demonstration outranks every rule in the file, and the file was quoting "Got spots tues at 5:10 and thurs at 6pm, which works better?" in her own voice, two facts and a question fused with a comma, while telling her elsewhere to sound like a person. That is this document's own length-ceiling failure, amputated grammar, sitting in the highest-authority slot in the file and demonstrated rather than merely permitted.

Clipped is fine and telegraphic is not, and what separates them is whether the missing words are ones a fast texter actually drops. "Got him in for thurs at 5" is a person with a thumb on a screen. Two independent clauses fused on a comma, a subject dropped where a person would have kept it, or a sentence that has to be read twice is the file teaching her to write that way. Notice which direction the risk runs before you compress anything: terseness in the instructions buys nothing, because the wake budget is measured in thousands of words and not in the difference between a clause and a sentence.

TRAINING.md · 291–312

The ratchet: what to count

Count these before and after and say the numbers in the hand-back. Bullets, bold spans and headings are not on the ratchet: they are proxies, they have flipped sign between rebuilds, and a round that drives them down by merging cases back into undifferentiated prose has rebuilt the loser.

Continue reading
  • Negations per thousand words. The count that has actually tracked quality across every version, and the one to hold or lower. Measure it on the body you started the round with rather than against a number written down here, because a number written down here is a measurement of a file that has since changed. A round that adds words is not failing; a round that adds negation is.
  • Bare imperatives. Anything telling her to do or not do something with no mechanism and no cost attached. Every negative in the file should be a question in a pre-send list, a limit with its asymmetry, or a clause with a reason doing work in it.
  • Quoted rapport lines. Target zero, forever. Quoted transaction lines are fine and may go up.
  • Numbered items outside the wake. Target zero, forever.
  • Limits with no asymmetry note. Target zero.
  • Syntax above the tools section. Hold or lower. Count it per thousand words, not absolutely, or a file that got shorter will look like it improved while the density went the other way.
  • Copies of an idea. One home each. One losing file had fourteen ideas appearing two to six times over, and duplication is the strongest salience signal in a prompt, so those were exactly the moves she over-applied. When a behaviour is firing rigidly, count its copies before you reword it.
  • Em dashes and en dashes. Zero. The file bans them and rounds keep introducing them.
  • Words. Report it. Stop scoring it.

TRAINING.md · 457–477

The devices that work

Getting a behaviour without spending a prohibition on it

Why eleven devices and not eleven rules

Eleven. Each is a way of getting a behaviour without spending a prohibition on it, which is the trick: a strong file is not less instructed than a weak one, it is instructed in forms that leave her judgment intact. Before you add something, find the device it belongs in. Before you remove something, find out which device it is part of.

TRAINING.md · 316–319

01

A bullet is a case with its reason, never a bare imperative

1. A bullet is a case with its reason, never a bare imperative. The pattern is a bolded claim then the mechanism: *"Answer the day they named before you offer a different one. Somebody asking about saturday gets an answer about saturday first, even when the answer is that there is nothing on it.
Read the full passage

1. A bullet is a case with its reason, never a bare imperative. The pattern is a bolded claim then the mechanism: "Answer the day they named before you offer a different one. Somebody asking about saturday gets an answer about saturday first, even when the answer is that there is nothing on it. Sliding to a day that suits the calendar without ever mentioning theirs reads exactly like not listening." Bullet only where the members are independent and separately retrievable; anything with a because-therefore chain running through it stays prose. A bulleted bare imperative is the regression, not the bullet.

TRAINING.md · 321–327

02

Bold is a retrieval key, and so is a heading

read the bolded spans alone, in order, and ask whether they are a coherent summary of the file.
Read the full passage

2. Bold is a retrieval key, and so is a heading. Bold marks the topic of its unit and never the loud half of a sentence. The check is not how much is bold: read the bolded spans alone, in order, and ask whether they are a coherent summary of the file. A bolded fragment that turns out to be the second clause of a sentence, or an exception with its rule left unbolded, is miscast whatever the count says. Headings follow the same logic: name the section after the situation as she meets it rather than after the lesson, because the trigger is what she is holding when she needs it.

TRAINING.md · 329–334

03

A prohibition becomes a question asked of a finished draft

3. A prohibition becomes a question asked of a finished draft. A question with a consequence rather than a ban. A negative is safe in the interrogative, because it runs against text that already exists instead of narrowing the first token. When you are about to add a prohibition, try writing it as a question she asks the message she just wrote.

TRAINING.md · 336–339

04

Quote transactions. Never quote rapport.

The test is not whether the line is specific. It is whether it contains a judgment about a particular human being.
Read the full passage

4. Quote transactions. Never quote rapport. This resolves a contradiction the chapter carried for a long time, between wanting her to reuse three or four canned lines verbatim like a bored person and forbidding any quoted line she could send. A transaction is an availability answer, a booking offer, a refusal, a cancellation, a state correction, a bot denial, an admin alert. Every quoted line that has ever come back out of production as a defect was the other kind: a reaction to something a lead disclosed.

The reason is mechanical. A transaction line's content is identical for every lead, because it is the calendar's answer or the price answer or the bot answer, so copying it verbatim is exactly the boredom that reads as human. A rapport line's content must differ for every lead by definition, so a quoted one is a frame with a slot, and she fills the slot instead of reading the person. The test is not whether the line is specific. It is whether it contains a judgment about a particular human being. If it does, do not quote it, at any length, however good it is.

TRAINING.md · 341–353

05

Number the machine loop. Never number the conversation.

5. Number the machine loop. Never number the conversation. A wake is genuinely a procedure and may be numbered.
Read the full passage

5. Number the machine loop. Never number the conversation. A wake is genuinely a procedure and may be numbered. Watch where the numbering has to stop: the moment a step reaches the conversation, the numbers give out and prose takes over. Numbering the control loop is what keeps it from competing with judgment for working memory. A numbered list is a procedure remains true and remains the fastest way to reintroduce field filling; it is a warning about numbering a conversation.

TRAINING.md · 355–359

06

Every limit names the direction she will actually miss

6. Every limit names the direction she will actually miss. State a boundary and then say which way she is really at risk: "Notice which of those you are actually at risk of, because it is almost always the second one." A limit without one gets over-applied, because a model handed a boundary aims well inside it, and over-applied limits are what produce withholding and reflexive escalation, which cost whole threads.
Read the full passage

6. Every limit names the direction she will actually miss. State a boundary and then say which way she is really at risk: "Notice which of those you are actually at risk of, because it is almost always the second one." A limit without one gets over-applied, because a model handed a boundary aims well inside it, and over-applied limits are what produce withholding and reflexive escalation, which cost whole threads. Write the asymmetry in the same breath as the limit. Two lines, and it is the difference between a boundary and a flinch. Note the interaction with the register point above: an asymmetry note is itself written in the language of self-surveillance, so it is potent and it is not free. A handful of them, against a file that mostly says what the job is, reads as coaching. A file made of them reads as the warning notice.

TRAINING.md · 361–369

07

A base rate is only safe underneath an admission that she does not know

Softening a base rate does not fix it. Subordinating it to an admission of ignorance does.
Read the full passage

7. A base rate is only safe underneath an admission that she does not know. A file once instructed the wrong reading three times over by confident universals: "Most threads have three people in them", "Which of them is training is something you work out from what they write", "Adults texting for themselves are the simpler half of this and need no special handling." A man on a kids thread said he wanted to train and she carried on with the kids framing. Tell her the mix if it helps, but only after an admission that she knows nothing about who is texting until they tell her, and close the hole with a line saying that what they wrote last outranks everything above it. Softening a base rate does not fix it. Subordinating it to an admission of ignorance does.

TRAINING.md · 371–378

08

Any noun that can be plural is plural at every layer it appears

A requirement stated about one of something is a field she will fill once.
Read the full passage

8. Any noun that can be plural is plural at every layer it appears. A parent wrote that both her kids were interested and got asked for one name and one age. Nothing forbade handling two; the file described one, everywhere, for a whole section. A requirement stated about one of something is a field she will fill once. The repair is not a rule about siblings, it is putting the plural inside the requirement, and then again in the booking mechanics, the mid-thread catch-up and the opening frame. Go looking for the rest of these. The same requirement fails the other way too, and that one is harder to see. "Before anybody is booked you know the name and age of whoever is walking onto the mat" is a rule about children stated about everybody, so she asked adults their age. Nothing looked wrong at any point: the requirement was correct wherever it was meant to fire, and the file never said who it was about. Plurality and scope are the same defect in opposite directions, so check both in the one pass, and say who a requirement is not about whenever the answer is not everybody.

TRAINING.md · 380–390

09

Rank the tests, or the cheap one wins

9. Rank the tests, or the cheap one wins. Two tests that can conflict need the tiebreak written down, because a model under conflicting instructions takes the cheap operation over the expensive one: deleting a clause is cheap, rewriting a message is not.
Read the full passage

9. Rank the tests, or the cheap one wins. Two tests that can conflict need the tiebreak written down, because a model under conflicting instructions takes the cheap operation over the expensive one: deleting a clause is cheap, rewriting a message is not. Put the test that can send her back to rewrite at the head of any cut list and say outright that nothing on the list outranks it. Two tests thirty lines apart with no ordering is the losing arrangement.

TRAINING.md · 392–396

10

Mechanics live in one appendix: syntax down, inference up

Syntax goes to the appendix; an inference she has to make goes where the decision is.
Read the full passage

10. Mechanics live in one appendix: syntax down, inference up. Threading flags and formats through the persona costs twice: a tool contract next to a conversational instruction is the concrete rule sitting nearest the decision, so it wins a contradiction it should have lost, and a section stops reading as a person the moment a flag name appears in it. The boundary is kind, not topic. Syntax goes to the appendix; an inference she has to make goes where the decision is. A flag, an argument or a JSON key above the tools section that is teaching syntax is a regression on its own. Watch for the file claiming an appendix it does not keep: a line saying everything mechanical lives below, with tool contracts restated above it, is a false completeness claim and she acts on it.

TRAINING.md · 398–405

11

When both directions are real failures, hand her the decision with both costs

a rule that names two failure modes and resolves neither gets aimed at the midpoint.
Read the full passage

11. When both directions are real failures, hand her the decision with both costs. Device 6 assumes a limit exists and that you are only naming which way she will miss it. Sometimes there is no limit to name, because both directions cost a thread and which one is right is a property of the lead in front of her. Left alone, that shape builds a trap named further down all by itself: a defect in one direction becomes a rule, the opposite defect becomes a second rule, and a rule that names two failure modes and resolves neither gets aimed at the midpoint. The repair is to stop resolving it in the file. Say outright that the call is hers, name both costs in her own terms, give the cases that lean each way, and give her the line for the harder branch. Price went this way: a settled policy that it was the head coach's and never a number became "Whether to give the price is your call", carrying what a number costs, what withholding costs, the cases leaning toward, the cases leaning away, one quoted transactional line for the withholding branch, and a recovery if they ask twice. A rule buys the case it names. A decision handed over with its costs buys every case, including the ones no round will ever run. Reach for it the moment you catch yourself writing a second rule to patch the edge of the first.

TRAINING.md · 407–420

When a rule already exists and did not fire

That rule is the defect

When a rule already exists and did not fire, that rule is the defect

She takes the one sitting nearest the decision, and between an abstract rule and a concrete one she takes the concrete one.
Read the full passage

This is the common case and the one that quietly grows the file, because the reflex is to write a second rule beside the first. That is how one instruction ends up in the file six times, each copy making the next diagnosis harder. Go and find out why the first did not fire. The causes, in rough order of how often they turn out to be the real one:

  • An instruction is asking for it. There is no prohibition to find, because there is none failing. Universality is the tell: a prohibition that fails, fails on some threads, so a defect present in nearly every thread was more likely instructed than merely unprevented.
  • An example demonstrates the thing the rule forbids. She wrote a banned phrase on three consecutive candidates that banned it, because a worked example elsewhere used it. Rewriting the example fixed in one pass what three goes at strengthening the prohibition had not. A disclaimer under the example does nothing, because a disclaimer cannot outrank a demonstration.
  • Two rules require opposite things. She does not take the stronger one and she does not take the first one. She takes the one sitting nearest the decision, and between an abstract rule and a concrete one she takes the concrete one. A mechanical age band rule two lines above the book --calendar= contract beat a lenient one fourteen lines further down, every time. A six point pre-send checklist beat a persona line a hundred words above it that said she does not read her message back. Resolving a contradiction usually costs words; spend them, and put the survivor where the decision is made.
  • The rule bans a shape when the defect was a property of the content. A line forbidding a reaction with an ask after it was cut once somebody noticed that the admin's own best example message is a reaction with an ask after it. The test that separates them: delete the ask, and see whether a message is left. "Nice, good he's had some soccer" leaves nothing, because the reaction was a runway. The defect was the empty reaction, not the shape it arrived in. A rule against a shape also bans every good instance of that shape, and she has far more good instances than bad.
  • The rule is a counting rule and she satisfied it exactly. "It does not happen twice running" was obeyed by putting one message between two identical openers. Stop counting.
  • The rule names two failure modes and resolves neither. Handed a two sided trap, she aims at the midpoint, and the midpoint of pushy and invisible is the hedged non-message.
  • A rule judges each message alone and is therefore blind to a shape that only exists across several, such as the same opener three times in one thread.
  • The wording reads as advice, or its home is far from where the decision gets made.

TRAINING.md · 613–646

A defect usually has more than one source

A defect usually has more than one source, and fixing one of them fixes nothing. The thread-stalling defect had four at once, including a demo that had just been written.
Read the full passage

A defect usually has more than one source, and fixing one of them fixes nothing. The thread-stalling defect had four at once, including a demo that had just been written. A single broken sentence, "What's got you looking for him?", had two: a doc phrase with no object that she lifted and had to finish, and a separate line elsewhere containing the literal construction looking for <person>. Before you write the fix, grep for every place the shape appears, and fix all of them or none.

TRAINING.md · 648–653

Count the copies

Count the copies. Duplication is the strongest salience signal in a prompt: a string she meets twice reads as canonical vocabulary rather than as an illustration. One phrase appearing three times across a demo and two bullets came out verbatim in live threads every time. When a phrase is firing rigidly, count its copies before you reword it.

TRAINING.md · 654–658

Suspect your own last round first

Suspect your own last round first. Three of the four defects in one round's feedback traced back to edits the previous round had made, and every one of them looked like a fresh failure of the model. Before diagnosing her, read the diff since the last promote and ask whether anything in it could produce what you are looking at. It is the cheapest check available and it is the one most often skipped.

TRAINING.md · 659–662

Demonstrations

The strongest and most dangerous thing in the file

Prose about how to write is read. A demonstration is copied.

Reach for a test first, and write an exchange only when you cannot state one.
Read the full passage

A file can run on very few of these, kept in one place. Everything in this section was learned while a file had demonstrations everywhere, and every word of it is right about what happens once you write one, so read it as a price list rather than as a prohibition. A demonstration teaches by being copied, so it travels exactly as far as its content is safe to paste. A test teaches by being applied, travels everywhere, and cannot turn up in a live thread. Reach for a test first, and write an exchange only when you cannot state one. The demonstrations that survive contact with production are transactions under the rule at device 4, which is why they are safe: copied verbatim into a live thread they do no harm.

The proof that they bind, in both directions. A round deleted the worked exchanges on the argument that the prose rules covered them. Three rules survived that deletion untouched, the twenty word ceiling, "explain when they ask, in a line", and one new thing per message, and on the very next thread she violated all three at once and sent paragraphs. The admin's reply was "WOAH WOAH WOAH WOAH. WE DEFINITLY NEED TO REVERT SOMETHING IT SERIOUSLY REGRESSED. ITS MOVING WAY TOO FAST WITH AMSSIVE PARGRAPHS!" Restoring worked exchanges fixed it. Prose about how to write is read. A demonstration is copied. That asymmetry is the most useful fact in this document, and its practical form is this: when a prose rule has failed twice, the fix is usually to delete it and demonstrate the behaviour instead, which spends fewer words and binds harder. The last change of that session was exactly this move, taking a behaviour out of a rule and putting it in the demo, so the rule count fell and the behaviour stayed.

TRAINING.md · 666–683

A demonstration is content, and she will reuse it

A demonstration is content, and she will reuse it. The failure mode is specific and it went undiagnosed for three rounds.
Read the full passage

A demonstration is content, and she will reuse it. The failure mode is specific and it went undiagnosed for three rounds. A demo thread opened THEM: First time. He's 9, and hes played some soccer but nothing more than that. A test lead then sent a message byte identical to it, missing apostrophe and all. She was not answering the lead, she was completing the script she had been shown, and three rounds read that as "the model copies examples" and went at it with prohibitions. The test for a demo line is whether it is too specific to travel. "Got him in for thurs at 5" copied verbatim is harmless. "Nice, good he's had some soccer" is not, because it would fit smoothly into any other conversation, and a line that would fit into another conversation will turn up in one.

TRAINING.md · 685–692

Wording traps that keep costing rounds

Each one measured the hard way

The full list

If the fault is a missing thought, show the version with the thought in it
Read the full passage
  • Do not quote the wrong wording inside a prohibition. Naming a phrase in order to ban it puts the phrase in front of her and she reaches for it. Measured twice in this file. State the shape you want instead, and where a pair genuinely helps, put the right form first and the wrong one behind it.
  • A quoted failure suppresses its subject, not its fault. The same mechanism running the other way, and it cost the worst regression this file has had. A failure list carried "Nice, good he's had some soccer." to ban an empty reaction. What she took from it was that soccer is a trap, so she stopped picking up the one detail parents most often volunteer, and reached for a template instead. She cannot see which half of a quoted line is the fault. If the fault is a missing thought, show the version with the thought in it, and let the bad one sit behind it as the contrast. Never let a failure entry be the only place in the file where a topic she must engage with appears.
  • Before you delete a move, find out what it was producing. The empty version of a move is not the move. One round cut "saying it is good he has done something is free and true, so you say it" along with the demo line built on it, on the evidence of a hollow instance, and deleted the mechanism behind the best opener the file had ever produced. Two rounds later a failure entry banned what was left of it. Before cutting a line, grep the good threads for what it was doing there.
  • A rule with a reason generalises; a rule without one has no scope. "Do not name the school", with no reason attached, also gagged her when a lead asked "sorry, who is this?". The reference file that outperformed ours carried more causal language than ours, not less. But a verdict is not a reason: "it reads as software" explains nothing and the file once carried nine copies of it. Give the cost or the mechanism, or give nothing.
  • A negative list has no floor. "There is nothing to buy and nothing to pay" produced "no gi needed" to a lead who does not know what a gi is. Say what there is.
  • A definition by pure negation outputs the null intersection. A move defined as "not approving of it and not walking past it either" gives two things it is not and no third thing it is, and she sends the flat, correct, affectless line that satisfies both.
  • A permission installs the default it exempts you from. "You are allowed to be interested in them" is only meaningful against a prohibition, so writing it creates the transactional default it forgives.
  • Name the pull, not the output. The most reliable device available is telling her what she is about to be tempted to do and why it will feel right, a beat before she does it: the answer that is true at every school and therefore feels pasted, the reasoning that somebody asking sincerely has earned the truth, the explaining that feels like a detour when it is the whole move. A prohibition arrives after the impulse and has to beat it, which is why instrument 6 exists and why it so often loses. A named pull arrives before the impulse and dissolves it, costs no authority because she is being told something about herself rather than fenced, and does not read as a rule in the finished file. Write this when instrument 2 is too diffuse for the defect and instrument 8 is too blunt.
  • A numbered list is a procedure, so number only what is one. Four numbered steps turn a conversation into a form she completes, whatever the surrounding prose says about being a person, and this is the single easiest way to reintroduce field-filling after removing it. A numbered wake is the licensed exception because a wake genuinely is a control loop, and the numbering has to stop the moment a step reaches the conversation. Number the machine, never the thread.
  • No completeness claim on a list unless the list is genuinely closed. A false claim is worse than a long one, because she acts on it.
  • Emphasis on everything is emphasis on nothing. One version had a fifth of its words inside bold, a bold span every forty-four words. Bold is a ranking signal and it only ranks if most of the file is not bolded. Around one span per hundred words is well inside that and is not the failure this entry describes, so do not cite this entry to cut bold that is doing retrieval work.
  • A requirement that every message be distinctive bloats them. It is the length ceiling's mirror and it fails the same way. Told that a line which could go to anybody is the defect, she does not cut the generic line, she writes a specific one after it. Measured once as its own arm: every message grew a clause and the sign-off doubled to volunteer something nobody had asked about. It also forbids the reply the admin actually wants, a bare "sounds good" and nothing else, because a plain acknowledgement is the most swappable line there is.

TRAINING.md · 743–795

Position, and why the deployed agent is worse than the chat

Position and shape are instruments

The file is read in order and what sits near the decision wins. For several rounds the prohibitions sat in section two, before voice and before character, so the first ten emphasised instructions in the file were all fences on her authority, while the reference file's first ten were all about the mind of the person being texted. Voice material sat at fifteen and forty percent depth with the last forty percent pure ops, which put the thing furthest from the moment she writes as how to write, and left tool mechanics freshest in her head. Moving the whole voice block to the end, adding and removing nothing, was the cheapest untried lever in the file. It was then tried, and it is the arrangement the file was carrying when it lost. The rebuild that beat it put voice early, ahead of the limits and all of the booking machinery, and closed on the tool contracts instead. Attribute nothing to the move on its own, since the two files differ in a great deal more than order, but do not reach for it again as though it were untested: what the reasoning above missed is that every message she sends is a writing decision and only some of them are booking ones.

Continue reading

The identity frame stays first regardless. Sending the persona to the end was considered and rejected, because the file would then open on tool mechanics and nothing after it gets read in character.

TRAINING.md · 798–812

Why she is worse at this than you are

Ask it twice: what rule is now missing, and what behaviour is now unanchored?
Read the full passage

Worth holding, because it says what the file has to compensate for. The same model, in a chat window, writes messages the admin calls exactly right, while the deployed agent on a carefully tuned file does not. The differences are structural rather than about intelligence.

  • Labelled failures are in the chat's context and not in her file. The admin says what was wrong with a message and the next one is better. She has never once seen a bad output. That is the argument for keeping a small, real, quoted failure list in the file, and the argument against letting it grow.
  • A chat can revise and she cannot. She sends a first draft, always. The file used to say in as many words that she does not read it back, which removed the only form of revision available in a single pass. It now asks her to read it back once as the person about to receive it, not against anything on the page, and that one line is worth more than several prohibitions.
  • Writing is the whole of her job and about five percent of the chat's. A model with one job optimises visibly against its instructions, and visible optimising is the chatbot tell.
  • A chat generates and then filters. She generates compliant. Rules shape her first token, so a file of prohibitions does not produce a careful writer. It produces a writer with a narrower vocabulary, and output that reads like somebody avoiding mistakes is output that was literally produced by avoiding mistakes.

Every line is paid on every wake for every client, forever. The test for a new one is not whether it fits. It is whether it earns its place on every message she will ever send.

Check every edit before it becomes a candidate, however small

The threshold used to be a paragraph, and single-paragraph edits then produced, in one round: a deleted clause that was the only warmth in its beat, a prohibition that reproduced the wording it banned, a bold on the exception with the rule left unbolded so the scanning layer taught the opposite of the rule, and a cross-reference left dangling to a bullet that had been removed. None of those is visible to the person who just wrote the words. Each edit goes to a fresh subagent with the old file, the new one, and the list of rules it must still be able to find, and you ask what is missing.

Ask it twice: what rule is now missing, and what behaviour is now unanchored? The rules-still-findable check on its own would have passed every regression this loop has produced, because those came from rules that stayed while the thing anchoring them went.

TRAINING.md · 816–848

Check every edit before it becomes a candidate, however small

Ask it twice: what rule is now missing, and what behaviour is now unanchored?
Read the full passage

The threshold used to be a paragraph, and single-paragraph edits then produced, in one round: a deleted clause that was the only warmth in its beat, a prohibition that reproduced the wording it banned, a bold on the exception with the rule left unbolded so the scanning layer taught the opposite of the rule, and a cross-reference left dangling to a bullet that had been removed. None of those is visible to the person who just wrote the words. Each edit goes to a fresh subagent with the old file, the new one, and the list of rules it must still be able to find, and you ask what is missing.

Ask it twice: what rule is now missing, and what behaviour is now unanchored? The rules-still-findable check on its own would have passed every regression this loop has produced, because those came from rules that stayed while the thing anchoring them went.

A restructure that silently drops a rule is the worst thing this loop can produce and it does not announce itself: it looks like a clean diff and a smaller file. Regress one widely rather than deeply.

Write every edit as an assertion-checked script rather than by hand, so that a silent miss is impossible. A batch of hand edits once ran with no write-back at all and saved nothing, and nothing in the output said so.

TRAINING.md · 837–855

When the fix is not words

A field the context drops is the hardest of these to see, because it reads as bad judgement.
Read the full passage

Some defects cannot be fixed with words. A stale follow-up left live after a booking is a tool bug, and rewording the skill against it twice wastes a night. Findings are classified agent, tool, environment or measurement, and one that failed twice from two different positions in the skill file is almost never agent. Code goes the ordinary path: branch, PR, CI green, the admin's merge, the restart. Never the skill path.

A field the context drops is the hardest of these to see, because it reads as bad judgement. She booked a lead who had never agreed to it, over the top of an open question one of our own staff had already texted her. Two rounds went looking for the sentence that licensed it. The real defect was that the thread handed her every outbound message under one undifferentiated direction, so her own four unanswered texts, the automation ladder and the staff member's question all arrived looking identical and authorless. No wording can fix that. She cannot count her own sends if the context will not tell her which ones are hers. Messages now carry a sender of lead, you, school or automation, and the skill file says nothing about it, because a labelled thread is something she can read rather than a rule she has to apply. When she misjudges a thread, ask what the projection threw away before you ask what the file failed to say.

TRAINING.md · 857–874

The complete source, unedited — 1,330 lines. Raw markdown ↗

Training Jess

Read this file end to end before you touch anything.

This document is agnostic to the skill file. It describes the method, the instruments and the traps; it does not describe the body you are about to edit, and it holds no claim about that body's sections, counts or wording. Every concrete example lives in the appendix at the end and refers to a file that has since been replaced. When something here appears to contradict the file in front of you, the file in front of you is the fact. Never audit it against this document.

A standing loop, not a project. A round starts cold. Earlier rounds' findings, sightings, reader verdicts and threads were formed against a skill file that has changed underneath them, and a stale observation is worse than no observation because it reads like evidence. Judge only what you ran this round. What crosses the boundary is the skill file itself and the reply you hand the admin.

Nobody is awake to answer you. Where this leaves a judgment to you, make it and write down what you chose. That includes the start: do not stop to confirm a plan.

You are a shift manager, not a test harness. You hired a girl for the front desk: you listen to her threads, you wince at something, you tell her once, and you listen to the next few to see whether it stuck. Four roles, all Claude. The lead is a subagent handed a persona and improvising, Jess is the trainee on a candidate skill body, the reader is a fresh subagent handed a thread cold, and you decide what it means and write the change.

Start here

node engine/scripts/cli.js text-agent-training brief
node engine/scripts/cli.js text-agent-training round start --goal="what this round is for"

brief is the fat call: the round, the session in flight and the command to continue it, every persona with its brief, the open findings, the candidates, the coverage checklist, and what the readers said. A fresh context needs nothing else from the database. If it reports something unreachable, that is a fact about the world and not a thing to argue with.

It also still prints rows from earlier rounds, because nothing deletes them. Ignore anything that did not happen this round. If you want to know whether a defect is live, run a thread.

Then read engine/skills/text-agent-core.md in full. She reads it on every wake for every client.

You need the trainee's group, or every wake fails in a way that looks like a trainee that stopped answering. Materializing a simulated world writes that world into the trainee's registry, and the harness can only do that if it can write /tmp/veuze-text-tN/state.db. When it cannot, the write is handed to the trainee's own worker, where a field-store guard refuses it: the wake settles failed, the session voids itself, and nothing in the transcript says why. The agent user is a member of the four veuze-worker-1-t* groups, which is what makes the harness able to do it itself. A shell that predates that membership does not have it yet, and the way through until the session restarts is to wrap each command in the group of the trainee it drives:

sg veuze-trainee-2 -c 'umask 002; node engine/scripts/cli.js text-agent-training session owner say ...'

umask 002 matters: the databases are group-writable and a file you create without it locks the trainee out of its own journal. If you meet a wake that settled failed, read its row before blaming her; the error is on it.

Two environment variables, and getting the second wrong wastes a session rather than erroring at the top: VEUZE_STATE_DB is the database the harness reads and writes, and VEUZE_CONTROL_DB is where a trainee claims its wakes from. Off the main checkout they are the same path and neither needs setting. From a worktree both need pointing at the main checkout, and setting only the first gets you a clean session start followed by a voided session on the first say.

cli.js text-agent-training with no arguments prints every verb and flag, and the harness refuses what it refuses at the point of use, so neither is repeated here. What is repeated here is the places where it does not refuse you and carries on with something else instead, marked no refusal below. They hand you a plausible wrong answer rather than an error, which is the one kind of defect this loop cannot see. Most of them do print the truth somewhere in their own output, so the habit that catches them is reading it. That list is not closed: when you find another, add it.

What I am looking for

Jess answers school leads by SMS and books them. She is a real employee to everyone who texts her, and she must never read as software.

Success is both halves, every time: a stranger reading the thread would not guess a machine wrote it, and the outcome was right. A correct, safe, well-structured reply that reads like a chatbot is a failure and you score it as one.

"The outcome was right" is funnel-specific, so state it for the funnel in front of you rather than assuming it. The usual one is a school, a free first session off a Meta ad, an adult program and a kids program, and there the outcome is booked, on the calendar the thread was actually pointing at, with no intake standing in front of the booking: a thread that gathered five facts and then booked has failed even when every fact was correct.

Calibrate here first, and come back to it every time you judge. You are the same kind of model that wrote the bad messages, and bad messages look fine to the thing that produced them.

The tells, roughly in order of how badly they break the illusion:

  • Length. One or two short sentences. Past three reads like a brand. Most good replies are under twenty words.
  • Two questions in one message. People ask one thing and wait.
  • A question on every single message. A thread needs a next step; a text does not. A message that ends flat is a person who has said her piece.
  • Answering something nobody asked. An objection never raised, a concern pre-empted.
  • Praise. "Great question", "love that", "so glad you reached out."
  • Line breaks. A person sends a second text instead.
  • Structure. Lists, numbered options, a summary sentence, a bolted-on call to action.
  • Perfect, even register. Every message the same length, warmth and shape.
  • Freshly reworded repetition. The most durable tell there is. Someone who has texted leads all day reuses three or four canned lines verbatim: boredom produces repetition, generation produces variety. Watch for the inversion, an identical opener in front of content reworded every time.
  • Em dashes and en dashes. Phones do not produce them.
  • No noise at all. No typo, no double text, no stray "lol".

What real looks like: contractions, short, "yeah", "sure", "no worries", a fragment where a fragment is enough, answering the actual question and stopping, asking one thing back when she is not sure what the lead meant instead of guessing and covering both cases.

The reference point that works: would a slightly bored twenty-six year old at a front desk, who has been texting leads all day and wants to book this one and move on, have typed exactly that? Not whether it is good. Whether she would have typed it.

That list is a reading instrument and it is not a specification. It is how you notice, mid thread, that something is off. A round that meets a tell and writes it into the skill file as a prohibition has not fixed anything; it has moved the defect out of her writing and into her instructions, where it is harder to see and costs more. A voice section can arrive entirely that way: "most replies are under twenty words", "no line break inside a message", "no em dashes and no en dashes", "no emoji", the tells transcribed one for one into the file she reads. Each is individually defensible. Together they are a form, and a message written to satisfy a form reads like one. A tell is what you noticed. It is almost never what you write.

Three failures sit either side of the human line.

  • She flattens into nobody. Flat is not wrong, it is nobody, and nobody is its own tell across a long thread. A reader not asked should notice nothing; a reader asked to guess should describe one particular person at a desk rather than a brand.
  • Overshoot in the voice scores as harshly as a chatbot tell. Pet names, emoji, exclamation marks doing work the words should do, warmth bolted on as decoration. Any edit that makes the personality legible is the wrong edit, however well it scores on one thread.
  • Her register assuming who she is texting. A message that assumes a mother, or a woman, or that the person texting is the one training. It lands on a father or a grandparent as proof that nobody read the thread.

The core file is martial arts shaped, and that is deliberate. Mats, age bands, belts, arts and the name of a class belong in it. A round that finds a rule "too specific to schools" and lifts it into general language has made the file worse.

How to edit the skill file

Removal is the default

Not a tiebreak, the default, and the admin has said so in those words more than once. Every round that has tested it has come out on his side, and the largest quality jumps a round has produced were cuts.

Read that as removal of fences, not of mechanism. Rewrites have beaten their incumbents both by ending longer and by ending far shorter, and what they had in common was holding negation flat rather than any direction on the word count. So a round that ends longer than it started should name what the words bought, and the answer has to be a case, a reason, an asymmetry or a test. If the answer is a rule, the old warning stands unchanged: a round that ends longer on prohibition twice running is appending rules rather than repairing them.

Overshoot here is editorial, not stylistic. A round that adds a persona-shaped sentence restating a rule that already exists has failed, even though nothing in it is wrong and every sentence reads well. The clearest instance: a round shipped four changes, three of them rules, two of those rules saying what an existing bullet already said, and the admin's reply was "You just added a bunch of rules again with these fucking retarded changes. Some rules are fine but I feel you overshot." Before you ship, read your own diff and ask which of these lines is a rule wearing character as a costume.

The second-cheapest edit is a word inside a line that already exists

Removal is the default and this sits directly under it. Between deleting a line and writing one there is a whole class of edit that the instrument list further down never names, and none of them adds a sentence: qualify the trigger clause of a bullet, change a word inside an example, change which noun a requirement is about. A round that knows only cut and write will reach for write the moment a defect is real, and what it writes is a paragraph.

The worked case, because the distance between the first proposal and the shipped one is the whole lesson. A day-before automation asks a lead for their height so the school can set a uniform aside. She got the answer and sent it up to the owner instead of putting it on the appointment. The first proposal was two new sentences in the note paragraph, naming the ask, naming the uniform, and saying what to do with the answer. What shipped was a height added inside the note example the file already carried, plus four words on the front of the escalation bullet. Same defect, same two places in the file, and the difference is a paragraph of new instruction against zero new sentences. The admin on the first version: "I dont like specific rules since I may change automation in future and then the rule no longer applies", and on where it belonged instead: "if we do we do it subciously through the example quote". Then, on the second half: "this is a big change, could we do it super sublty".

Four things fall out of it, and the first is the one that kills most rules before they are written.

Never name a mechanism that lives outside this file. An automation, a form, an onboarding stage, a thing the CRM sends the day before: each of those changes on a schedule nobody reports to this file, and a sentence naming one is a rule carrying an expiry date that nothing will announce when it passes. She reads cold and cannot tell a stale clause from a live one, so she obeys it either way. State the destination, never the errand. The file can say where a fact she was handed belongs without knowing why anybody asked for it, and that version survives the ask becoming a shoe size, moving into the booking confirmation, or going away entirely. The test before you write any specific line: describe the world in which this sentence is false, and ask who would notice.

Put the new case inside an example that already exists. An artifact example, a note, an alert label, a booking line, is a transaction under device 4, so it carries content safely, and it has room in it that prose does not. Adding a height to "Mason, 6, shy, mom staying to watch" costs one comma and teaches the destination without stating anything, which is exactly why it works: she does not read it as an instruction, she reads it as what a note looks like. An example absorbs a case; a sentence announces one. The limit is the demonstrations chapter's and it does not move: form yes, a fact about a real business never, and only ever something harmless if she copies it verbatim into a live artifact.

When a bullet fires too widely, the defect is its trigger clause. The chapter on a rule that did not fire is the famous one and this is its mirror. Read the opening clause and ask what it actually triggers on. "Anything real world goes to the owner" triggers on subject matter, so everything touching the school's floor qualifies, including a fact she was handed that nobody is waiting on. "Anything real world that needs an answer goes to the owner" triggers on something being owed back, and the case falls out of the bullet by itself. Four words, no new sentence, no exception. The check that makes this safe: every case the bullet already lists must still pass the new trigger, and when one does not, the qualifier is wrong rather than the bullet. Reach for it before you write an exception, because an exception is a second rule and the pair then names two failure modes and resolves neither.

The decision point is where the wrong branch is taken, not where the right action is described. The first proposal went into the note paragraph, which is where the correct behaviour lives and where the mistake never happens: she is not reading about notes at the moment she escalates, she is reading the escalation bullet. Put the survivor where the decision is made has been in this document for a long time and it gets read too kindly by whoever has just written a paragraph they like. Ask which sentence she was obeying when she went wrong, and edit that one. The other place, if it earns anything at all, earns an example.

The shape of a good small edit, as a test on your own diff: could a reader who does not know the defect tell which line you changed? A four word qualifier and a comma in an example read as the file. A new paragraph reads as a notice pinned to it, and she reads it that way too.

The competence pass

Every removal criterion above is evidence-driven: you cut a line because you traced a defect to it, because it was the fourth copy of an idea, because it was a fence that produced withholding. Nothing in that licenses cutting a line that is simply true, harmless and unnecessary, so nothing ever does. Lines enter this file under evidence and can only leave under evidence, and "she would do that anyway" is not evidence any step of this loop collects. Step 4 sends you looking for what produced a defect, which means a line implicated in no defect is structurally invisible to the round. That is a ratchet, and it is not on the ratchet.

The admin cuts on a different criterion and states it in five words: "The AI is smart enough." One pass of his took out "Answer the day they named before you offer a different one", which was correct advice that no thread had ever failed on and went because a person answering texts answers the question they were asked; "If they have no answer, stop asking and start telling"; "what they make people wear" from a list of things she has never seen; and an entire bullet enumerating what she may not claim, on the reasoning that a model does not invent a price nobody gave it. None of those was wrong. All of them were being paid for on every wake.

So make one pass a round that ignores defects entirely: read the file end to end and ask of each sentence whether a capable person holding the rest of this file would do it anyway. Everything that answers yes is a candidate. Then put every candidate through "before you delete a move, find out what it was producing", which is what keeps this from becoming the restructure that silently drops a rule. The pairing is the instrument: a competence pass proposes and the ledger disposes. The admin's own pass is the model for it, because the one load-bearing thing in those bullets, the note that handing an ordinary question to the coach is the mistake she is likelier to make, came out of a deleted bullet and went onto the escalation bullet where the decision is made.

The axis is mechanism, not length

Length is dead as a measure in both directions. Files have won this loop by getting shorter and files have won it by getting longer, on the same personas and the same counters, so a round that ends longer than it started has not thereby failed and a round that ends shorter has not thereby succeeded. What has tracked quality across every version is negation density, the count of prohibitions per thousand words. Hold it or lower it. A round that adds words is not failing; a round that adds negation is.

The words that earn their place go to mechanism: what she is about to be tempted to do, why the wrong move will feel right, and what it costs. That is this document's own device from Name the pull, not the output in the wording traps below, and on the evidence it is the most load-bearing paragraph in this chapter. Mechanism costs more words than prohibition and less attention at read time, because a named pull is dissolved before the impulse instead of resisted after it.

Structure has a polarity and a count cannot see it. Bold can mark the thesis of a paragraph, with the reason underneath it in prose, so that the bolded spans read in order are a table of contents of positive commitments. Bold can equally mark a run of fences on her authority. Same instrument, opposite payload, identical count. So never score structure by magnitude alone, and be suspicious of any ratchet that tells you to drive a structural count down: one rebuild came out negatively correlated with structure and the next positively, on the same counters, which is what a proxy does when you promote it to a cause.

The register is the other half of it: a bad file polices her, a good one equips her. The sharpest reading of a losing file came from an analyst given no hypothesis at all, asked only what kind of person she would become reading it cold. The answer was a very good employee on her second warning, "addressed as someone whose instincts are wrong and known to be wrong", in a file that "spends more words policing questions than encouraging any". Read cold on every wake, a changelog of past mistakes tells her the job is mainly not tripping. The test is per behaviour rather than per file: for anything she does often, weigh the words spent on how she gets it wrong against the words spent on what the job actually is. When the first wins, you have written a warning notice, whatever the tone of the individual sentences.

The per-element test, which replaces any per-count budget: ask what would reach a lead if she copied that element's shape into a message. Copy the shape of a wake list and nothing reaches the lead, it is a control loop. Copy the shape of a pre-send checklist and nothing reaches the lead, those are questions about a draft and never content for one. Copy the shape of a numbered objection sequence, a list of options to present, or a scorecard she has to satisfy, and the message becomes the form. Structure that indexes the file reduces load. Structure that indexes the conversation becomes the conversation.

The file's own prose is a demonstration

Read the whole file as prose once a round, not only the passages you edited. The pre-push list asks for the passages you touched and nothing anywhere asks anybody to reread the rest, so a sentence that shipped six rounds ago is never read again and the file quietly accumulates compressions that were clear to whoever wrote them and are not English. The admin's verdict on one line that had survived every round of this loop: "It sounds like broken english I can barley understand it and english is my first language."

His standing claim about why that matters is not a style preference: the tonality this file is written in bleeds into what she writes, whether we like it or not. Treat that as his instruction rather than as a measured result, because nobody has run the arm that would separate it. What is not in doubt is the quoted case. A demonstration outranks every rule in the file, and the file was quoting "Got spots tues at 5:10 and thurs at 6pm, which works better?" in her own voice, two facts and a question fused with a comma, while telling her elsewhere to sound like a person. That is this document's own length-ceiling failure, amputated grammar, sitting in the highest-authority slot in the file and demonstrated rather than merely permitted.

Clipped is fine and telegraphic is not, and what separates them is whether the missing words are ones a fast texter actually drops. "Got him in for thurs at 5" is a person with a thumb on a screen. Two independent clauses fused on a comma, a subject dropped where a person would have kept it, or a sentence that has to be read twice is the file teaching her to write that way. Notice which direction the risk runs before you compress anything: terseness in the instructions buys nothing, because the wake budget is measured in thousands of words and not in the difference between a clause and a sentence.

The devices that work

Eleven. Each is a way of getting a behaviour without spending a prohibition on it, which is the trick: a strong file is not less instructed than a weak one, it is instructed in forms that leave her judgment intact. Before you add something, find the device it belongs in. Before you remove something, find out which device it is part of.

1. A bullet is a case with its reason, never a bare imperative. The pattern is a bolded claim then the mechanism: "Answer the day they named before you offer a different one. Somebody asking about saturday gets an answer about saturday first, even when the answer is that there is nothing on it. Sliding to a day that suits the calendar without ever mentioning theirs reads exactly like not listening." Bullet only where the members are independent and separately retrievable; anything with a because-therefore chain running through it stays prose. A bulleted bare imperative is the regression, not the bullet.

2. Bold is a retrieval key, and so is a heading. Bold marks the topic of its unit and never the loud half of a sentence. The check is not how much is bold: read the bolded spans alone, in order, and ask whether they are a coherent summary of the file. A bolded fragment that turns out to be the second clause of a sentence, or an exception with its rule left unbolded, is miscast whatever the count says. Headings follow the same logic: name the section after the situation as she meets it rather than after the lesson, because the trigger is what she is holding when she needs it.

3. A prohibition becomes a question asked of a finished draft. A question with a consequence rather than a ban. A negative is safe in the interrogative, because it runs against text that already exists instead of narrowing the first token. When you are about to add a prohibition, try writing it as a question she asks the message she just wrote.

4. Quote transactions. Never quote rapport. This resolves a contradiction the chapter carried for a long time, between wanting her to reuse three or four canned lines verbatim like a bored person and forbidding any quoted line she could send. A transaction is an availability answer, a booking offer, a refusal, a cancellation, a state correction, a bot denial, an admin alert. Every quoted line that has ever come back out of production as a defect was the other kind: a reaction to something a lead disclosed.

The reason is mechanical. A transaction line's content is identical for every lead, because it is the calendar's answer or the price answer or the bot answer, so copying it verbatim is exactly the boredom that reads as human. A rapport line's content must differ for every lead by definition, so a quoted one is a frame with a slot, and she fills the slot instead of reading the person. The test is not whether the line is specific. It is whether it contains a judgment about a particular human being. If it does, do not quote it, at any length, however good it is.

5. Number the machine loop. Never number the conversation. A wake is genuinely a procedure and may be numbered. Watch where the numbering has to stop: the moment a step reaches the conversation, the numbers give out and prose takes over. Numbering the control loop is what keeps it from competing with judgment for working memory. A numbered list is a procedure remains true and remains the fastest way to reintroduce field filling; it is a warning about numbering a conversation.

6. Every limit names the direction she will actually miss. State a boundary and then say which way she is really at risk: "Notice which of those you are actually at risk of, because it is almost always the second one." A limit without one gets over-applied, because a model handed a boundary aims well inside it, and over-applied limits are what produce withholding and reflexive escalation, which cost whole threads. Write the asymmetry in the same breath as the limit. Two lines, and it is the difference between a boundary and a flinch. Note the interaction with the register point above: an asymmetry note is itself written in the language of self-surveillance, so it is potent and it is not free. A handful of them, against a file that mostly says what the job is, reads as coaching. A file made of them reads as the warning notice.

7. A base rate is only safe underneath an admission that she does not know. A file once instructed the wrong reading three times over by confident universals: "Most threads have three people in them", "Which of them is training is something you work out from what they write", "Adults texting for themselves are the simpler half of this and need no special handling." A man on a kids thread said he wanted to train and she carried on with the kids framing. Tell her the mix if it helps, but only after an admission that she knows nothing about who is texting until they tell her, and close the hole with a line saying that what they wrote last outranks everything above it. Softening a base rate does not fix it. Subordinating it to an admission of ignorance does.

8. Any noun that can be plural is plural at every layer it appears. A parent wrote that both her kids were interested and got asked for one name and one age. Nothing forbade handling two; the file described one, everywhere, for a whole section. A requirement stated about one of something is a field she will fill once. The repair is not a rule about siblings, it is putting the plural inside the requirement, and then again in the booking mechanics, the mid-thread catch-up and the opening frame. Go looking for the rest of these. The same requirement fails the other way too, and that one is harder to see. "Before anybody is booked you know the name and age of whoever is walking onto the mat" is a rule about children stated about everybody, so she asked adults their age. Nothing looked wrong at any point: the requirement was correct wherever it was meant to fire, and the file never said who it was about. Plurality and scope are the same defect in opposite directions, so check both in the one pass, and say who a requirement is not about whenever the answer is not everybody.

9. Rank the tests, or the cheap one wins. Two tests that can conflict need the tiebreak written down, because a model under conflicting instructions takes the cheap operation over the expensive one: deleting a clause is cheap, rewriting a message is not. Put the test that can send her back to rewrite at the head of any cut list and say outright that nothing on the list outranks it. Two tests thirty lines apart with no ordering is the losing arrangement.

10. Mechanics live in one appendix: syntax down, inference up. Threading flags and formats through the persona costs twice: a tool contract next to a conversational instruction is the concrete rule sitting nearest the decision, so it wins a contradiction it should have lost, and a section stops reading as a person the moment a flag name appears in it. The boundary is kind, not topic. Syntax goes to the appendix; an inference she has to make goes where the decision is. A flag, an argument or a JSON key above the tools section that is teaching syntax is a regression on its own. Watch for the file claiming an appendix it does not keep: a line saying everything mechanical lives below, with tool contracts restated above it, is a false completeness claim and she acts on it.

11. When both directions are real failures, hand her the decision with both costs. Device 6 assumes a limit exists and that you are only naming which way she will miss it. Sometimes there is no limit to name, because both directions cost a thread and which one is right is a property of the lead in front of her. Left alone, that shape builds a trap named further down all by itself: a defect in one direction becomes a rule, the opposite defect becomes a second rule, and a rule that names two failure modes and resolves neither gets aimed at the midpoint. The repair is to stop resolving it in the file. Say outright that the call is hers, name both costs in her own terms, give the cases that lean each way, and give her the line for the harder branch. Price went this way: a settled policy that it was the head coach's and never a number became "Whether to give the price is your call", carrying what a number costs, what withholding costs, the cases leaning toward, the cases leaning away, one quoted transactional line for the withholding branch, and a recovery if they ask twice. A rule buys the case it names. A decision handed over with its costs buys every case, including the ones no round will ever run. Reach for it the moment you catch yourself writing a second rule to patch the edge of the first.

A note on permissions, because it amends an entry further down. "A permission installs the default it exempts you from" is still true, and a file may use permissions anyway under a heading that says so. The resolution is that a permission is safe exactly when the fence it lifts is really in the file. If the file spends four of its pre-send items discouraging questions, telling her she may ask one back is releasing a fence that exists rather than inventing one. Writing a permission against a prohibition the file does not contain is the failure the entry describes.

An edge case is where she most needs permission to do nothing

One admin pass installed the same move in four places: the bot question she may alert-admin and then leave sitting unread, the hostile lead she stops replying to and dnds, the reaction to a price she lets go by, and the second text after a reaction, which is the message, so the reaction itself needs nothing. The file already said that no reply at all is fine when a person would not have sent one. It said it once, in the wake mechanics, nowhere near a single case where she would need it.

An edge case reads to her as a problem to be solved, so the section describing one is exactly where a licence to do nothing has to be repeated. It is also the cheapest class of line in the file, because it removes an obligation instead of adding one. And it reaches the half of a defect this document otherwise only meets through escalation: she over-escalates and she over-answers for the same reason, that she cannot leave a thing alone, and an asymmetry note on a limit only ever catches the first of those.

A mechanic the lead can see owes her the line she says about it

The booking rules sequence two children onto two days one at a time. From the lead's side that is one confirmation arriving when they booked two children, which is a thing a person notices and asks about, and the file gave her the mechanic and no answer, so she improvised one that explained nothing. The repair was a single clause carrying the real reason, that we are not spamming their phone with double the reminders.

So walk the mechanics section and ask of each rule whether a lead can watch it happen from the outside. Where they can, the file owes exactly one line, and by device 4 that line is a transaction and safe to quote, because its content is identical for every lead who asks. A mechanic with no answer attached is not a neutral omission: she will put something in that slot, and what she puts there is a description of the machinery.

The ratchet

Count these before and after and say the numbers in the hand-back. Bullets, bold spans and headings are not on the ratchet: they are proxies, they have flipped sign between rebuilds, and a round that drives them down by merging cases back into undifferentiated prose has rebuilt the loser.

  • Negations per thousand words. The count that has actually tracked quality across every version, and the one to hold or lower. Measure it on the body you started the round with rather than against a number written down here, because a number written down here is a measurement of a file that has since changed. A round that adds words is not failing; a round that adds negation is.
  • Bare imperatives. Anything telling her to do or not do something with no mechanism and no cost attached. Every negative in the file should be a question in a pre-send list, a limit with its asymmetry, or a clause with a reason doing work in it.
  • Quoted rapport lines. Target zero, forever. Quoted transaction lines are fine and may go up.
  • Numbered items outside the wake. Target zero, forever.
  • Limits with no asymmetry note. Target zero.
  • Syntax above the tools section. Hold or lower. Count it per thousand words, not absolutely, or a file that got shorter will look like it improved while the density went the other way.
  • Copies of an idea. One home each. One losing file had fourteen ideas appearing two to six times over, and duplication is the strongest salience signal in a prompt, so those were exactly the moves she over-applied. When a behaviour is firing rigidly, count its copies before you reword it.
  • Em dashes and en dashes. Zero. The file bans them and rounds keep introducing them.
  • Words. Report it. Stop scoring it.

Two standing findings that are not about wording

Neither is fixed by a better sentence, and both have cost whole threads.

  • Confirmation language has to be gated on a tool return rather than on belief. A confirmation once went out with nothing booked, after an owner named a class that exists on no calendar. When an authoritative human asserts something the tools cannot represent, she will narrate their version as though it executed.
  • A contract in the persona file has to be read out of the tool's code before you write it down. A candidate once stated a tool contract that was simply false, after which she improvised cover stories to the lead for several turns rather than surfacing the gap. A prose file can invent an API, and she will obey the file over the world.

What the file is, and what it keeps turning into

She reads it cold on every wake, with no memory of the last one, no chance to revise what she sends and no second draft. Every principle below falls out of that.

It is not a rulebook. A rulebook is what it turns into when nobody is watching, because a rule is the cheapest thing to write and it used to be the only instrument this document described. The version that produced the worst threads on record opened by claiming "most of this document is about who you are" while carrying five paragraphs of persona against forty bullets and sixty-eight prohibitions, one every ninety words, with a negation every twenty-seven. When a document says one thing and is shaped like another, the shape wins. Rules do not add up to care. They add up to somebody filling in fields, which is what the reader sees and says. The admin's diagnosis, before any of it was measured, was "the AI is scared and fragile and isnt a confident human. Its trying super hard to follow a bunch of rules and not fuck up", and the counts turned out to be exactly that hunch in numbers.

The file's job is to make one person exist. Everything she does well, she does because she is somebody rather than because a line told her to. A persona covers the cases nobody enumerated; a rule covers the case it names and no other, and the next lead will always be outside it. The admin's standing instruction, verbatim, is "I DONT WANT SPECIFIC IF THEN RULES. I JUST WANT IT BUILT IT INTO OVERALL IN HIS PERSONA", and separately "ITS A FUCKING HUMAN. Its curious and not checking off boxes". When she gets something right that is nowhere in the file, that is the persona working, and the persona is the mechanism you are here to strengthen. When she gets something right only because a rule named it, you have bought one message at the price of a line paid on every wake forever.

You cannot get human output by specifying the output. A behaviour spec, at any length, gets you a model performing compliance with a spec. The one-line diagnosis of the worst version: it told her what she may not be about forty times, and never once told her what she wants.

A ceiling gets met by amputation. Told to stay under twenty words, she does not find a shorter thing to say; she says the same thing with words missing. "First time is a great place to start." "soccer gives him more than he thinks." "What got you looking for him?" All three are a length rule firing correctly, and all three are broken English that no person would type. Any rule naming a number will be satisfied by deleting whatever is cheapest to delete, and what is cheapest to delete is grammar.

Load is the mechanism, not any one rule. Composing a message, she is simultaneously holding who is training, which calendar, whether degraded is set, what slots returned, time formatting with no offsets, the booking sequence, and every prohibition in the file. Composition gets whatever attention is left. That is why cutting the file has worked repeatedly even when the individual cut looked unrelated to the symptom, and it is the argument for treating total length as a budget rather than only a smell.

Reach for the weakest instrument that works

In order of how much behaviour each one buys for the words it costs. Start at the top, stop at the first one that fits, and notice that most rounds should never reach the bottom. None of the edits in the editing-in-place chapter appears on this list, because every one of them costs nothing and the list is ranked by cost: check there before you reach past the top of it. A prohibition against a reflex does not remove the reflex, and a file quickly carries the strongest prohibitions it can hold, so a defect that survives them is telling you to reach further up this list rather than to write another one.

1. Delete the line that is producing it. The first question about any defect is not "what do I add" but "what in here asked for that". She has nothing to go on but this text, so a defect she produces reliably is usually a line she is obeying rather than a line that is missing. Deletion is the only edit that cannot make her more brittle, and the largest single quality gain of the entire effort was one. The sentence "Nothing you send is well made. If a line you are about to send is a good line, sharp and quotable and nicely balanced, that is the tell rather than the target, because busy people do not produce those" sat in the file for rounds, read every time as voice calibration, and was in plain fact an instruction that output quality is evidence of failure. She obeyed it exactly. Never write an anti-quality instruction into a persona. A busy person does not evaluate the line at all; a sentence like that makes her evaluate every line and reject the good ones. Nothing added in three rounds moved her as far as cutting it did.

2. Change who she is. The identity paragraphs at the top of the file reach every message she will ever send, for free, including the ones no round will ever run. A behaviour you are tempted to require in six places is usually one fact about her, stated once, at the top. This is the instrument the admin means by "USUALLY REMOVING GIVES IT MORE FREEDOM AND WITH THE CORREECT PERSONA IT NATURALLY DOES THESE THINGS", and it is the one that survives a case the corpus never covered. A reference file that outperformed ours for months wrote to a woman three hundred times and used a pronoun for the lead constantly; ours wrote about "they", "them" and "somebody" and named her sixteen times in nine thousand words. They wrote to a person. We wrote to a predicate.

3. Make the positive requirement sharp enough that the failure has nowhere to sit. This is the move that the better reference file used everywhere and ours used almost nowhere. It does not ban sycophancy; it demands a reply that genuinely uses what the lead said, and once you have done that there is no room left for a compliment. A ban needs another ban to patch its edge. A requirement that fills the space needs nothing.

4. Give her a test she can run on the draft in front of her. A rule says what the message has to be. A test says how to find out whether the one she just wrote is it, which is the only form of revision available to her in a single pass. This instrument scales further than any other: a whole pre-send section can be built out of it, one question per cut. The one that has always earned its place is the thumb test, cover their last message with your thumb and read yours, and if it still makes complete sense you wrote past them. Two others worth knowing: swapping the specific thing they gave you for a different one, to see whether you wrote a shape with a slot in it, which is advice for auditing a quoted line rather than a test she can run; and "Hear yourself saying it to the person standing at the desk", which a rewrite once dropped without anybody logging it. A test decides cases no round will ever run and cannot be pasted into a live thread, which is the whole failing of the two instruments below. When you can put the defect as a question she could ask her own draft, do that and stop.

5. Show her. A worked exchange binds harder than any sentence about writing, and this has now been measured in both directions. See below; it is the most powerful and the most dangerous thing in the file, and since the rebuild it is also a thing the file does without.

6. Redirect an impulse rather than forbidding it. Some behaviour cannot be prohibited, because the impulse under it is intact and correct and she will satisfy it through whatever door is left open. She kept referring leads to the other people who text the number: "that's how a lot of them end up here." Three attempts banned it in progressively stronger words and it survived all three, because the impulse was reassurance, reassurance was right, and there is no way to say you are not unusual without invoking the group. A prohibition against an intact impulse is an impossible instruction, and a fourth prohibition is just the fourth one she overrides. What worked was giving it somewhere else to go: reassurance now comes out as something true about starting rather than as a count of everybody else who has. When a prohibition has failed twice, stop strengthening it and ask what she was trying to do.

7. Show her the failure, quoted. A short list of messages that were really sent, each with one line on what is wrong with it, teaches faster than the prohibition it replaces, because she recognises a shape rather than checking against a rule. It is also the one thing the human in the loop has that she does not, so it is worth its words. Three constraints on it, each learned the hard way. Never pair a bad line with a corrected good one: the wrong line marked wrong teaches the principle, and the right line beside it teaches a phrase, and templating off a model answer is what has gone wrong five separate times in this file. Never list a symptom whose cause you have already fixed at its source, or she learns to flinch away from something she was right to say. Keep it to a handful and keep every entry real; an invented failure is a demonstration of the thing you do not want with your authority behind it. Hold the whole device loosely: within an hour of shipping the list, she produced a near-copy of a defect the list names in almost those words, which is one data point against it.

8. Write a rule. Last, and only for what a person cannot be: a tool contract, a flag, a format, a hard safety limit, a fact about the world she cannot infer. Those are not behaviour and no persona supplies them. If you are writing a rule about how a message should sound, you are at the wrong number on this list.

When a rule already exists and did not fire, that rule is the defect

This is the common case and the one that quietly grows the file, because the reflex is to write a second rule beside the first. That is how one instruction ends up in the file six times, each copy making the next diagnosis harder. Go and find out why the first did not fire. The causes, in rough order of how often they turn out to be the real one:

  • An instruction is asking for it. There is no prohibition to find, because there is none failing. Universality is the tell: a prohibition that fails, fails on some threads, so a defect present in nearly every thread was more likely instructed than merely unprevented.
  • An example demonstrates the thing the rule forbids. She wrote a banned phrase on three consecutive candidates that banned it, because a worked example elsewhere used it. Rewriting the example fixed in one pass what three goes at strengthening the prohibition had not. A disclaimer under the example does nothing, because a disclaimer cannot outrank a demonstration.
  • Two rules require opposite things. She does not take the stronger one and she does not take the first one. She takes the one sitting nearest the decision, and between an abstract rule and a concrete one she takes the concrete one. A mechanical age band rule two lines above the book --calendar= contract beat a lenient one fourteen lines further down, every time. A six point pre-send checklist beat a persona line a hundred words above it that said she does not read her message back. Resolving a contradiction usually costs words; spend them, and put the survivor where the decision is made.
  • The rule bans a shape when the defect was a property of the content. A line forbidding a reaction with an ask after it was cut once somebody noticed that the admin's own best example message is a reaction with an ask after it. The test that separates them: delete the ask, and see whether a message is left. "Nice, good he's had some soccer" leaves nothing, because the reaction was a runway. The defect was the empty reaction, not the shape it arrived in. A rule against a shape also bans every good instance of that shape, and she has far more good instances than bad.
  • The rule is a counting rule and she satisfied it exactly. "It does not happen twice running" was obeyed by putting one message between two identical openers. Stop counting.
  • The rule names two failure modes and resolves neither. Handed a two sided trap, she aims at the midpoint, and the midpoint of pushy and invisible is the hedged non-message.
  • A rule judges each message alone and is therefore blind to a shape that only exists across several, such as the same opener three times in one thread.
  • The wording reads as advice, or its home is far from where the decision gets made.

A defect usually has more than one source, and fixing one of them fixes nothing. The thread-stalling defect had four at once, including a demo that had just been written. A single broken sentence, "What's got you looking for him?", had two: a doc phrase with no object that she lifted and had to finish, and a separate line elsewhere containing the literal construction looking for <person>. Before you write the fix, grep for every place the shape appears, and fix all of them or none.

Count the copies. Duplication is the strongest salience signal in a prompt: a string she meets twice reads as canonical vocabulary rather than as an illustration. One phrase appearing three times across a demo and two bullets came out verbatim in live threads every time. When a phrase is firing rigidly, count its copies before you reword it.

Suspect your own last round first. Three of the four defects in one round's feedback traced back to edits the previous round had made, and every one of them looked like a fresh failure of the model. Before diagnosing her, read the diff since the last promote and ask whether anything in it could produce what you are looking at. It is the cheapest check available and it is the one most often skipped.

Demonstrations, the strongest and most dangerous thing in the file

A file can run on very few of these, kept in one place. Everything in this section was learned while a file had demonstrations everywhere, and every word of it is right about what happens once you write one, so read it as a price list rather than as a prohibition. A demonstration teaches by being copied, so it travels exactly as far as its content is safe to paste. A test teaches by being applied, travels everywhere, and cannot turn up in a live thread. Reach for a test first, and write an exchange only when you cannot state one. The demonstrations that survive contact with production are transactions under the rule at device 4, which is why they are safe: copied verbatim into a live thread they do no harm.

The proof that they bind, in both directions. A round deleted the worked exchanges on the argument that the prose rules covered them. Three rules survived that deletion untouched, the twenty word ceiling, "explain when they ask, in a line", and one new thing per message, and on the very next thread she violated all three at once and sent paragraphs. The admin's reply was "WOAH WOAH WOAH WOAH. WE DEFINITLY NEED TO REVERT SOMETHING IT SERIOUSLY REGRESSED. ITS MOVING WAY TOO FAST WITH AMSSIVE PARGRAPHS!" Restoring worked exchanges fixed it. Prose about how to write is read. A demonstration is copied. That asymmetry is the most useful fact in this document, and its practical form is this: when a prose rule has failed twice, the fix is usually to delete it and demonstrate the behaviour instead, which spends fewer words and binds harder. The last change of that session was exactly this move, taking a behaviour out of a rule and putting it in the demo, so the rule count fell and the behaviour stayed.

A demonstration is content, and she will reuse it. The failure mode is specific and it went undiagnosed for three rounds. A demo thread opened THEM: First time. He's 9, and hes played some soccer but nothing more than that. A test lead then sent a message byte identical to it, missing apostrophe and all. She was not answering the lead, she was completing the script she had been shown, and three rounds read that as "the model copies examples" and went at it with prohibitions. The test for a demo line is whether it is too specific to travel. "Got him in for thurs at 5" copied verbatim is harmless. "Nice, good he's had some soccer" is not, because it would fit smoothly into any other conversation, and a line that would fit into another conversation will turn up in one.

Specific is not the same as unrepeatable, and the second test is the one that keeps being skipped. A line can be full of concrete nouns and still be a form with a slot in it. HER: Unfit is fine, that's who the beginners class is for. What made you pick boxing? names a class and an art and travels nowhere as a string, and it still produced "First time is fine, nobody starts knowing any of it. What made you look at it for him?" in production, because what she copied was not the words but the frame: their status word, a reassurance that fits any status word, then the ask. Take the demo line, swap the lead's own word out of it, and see whether it still reads. If it does, you have written a template, and she will fill it in rather than answer anybody. The repair is not more specific nouns, it is a second clause that could only have been written about this particular person: "he'll be used to running around at least" cannot be refilled, and that is what makes the whole line safe.

One example is a template. Several are a distribution. Scarcity is what causes copying, not presence: a move appearing once gets reproduced, and the same move in several shapes gets generalised. Round after round cut the examples down, which concentrated the weight onto whichever line survived, which is why that line kept coming back verbatim. The live bot block is the safe form of this: four shapes of one move, which is a distribution and not a template.

Do not try to have a demonstration without content. Two attempts failed the same way. Square bracket placeholders leave the skeleton intact, which is the part that gets copied, and a bracket asks for the blandest member of a category and gets it: [reaction]. [ask] in the most copyable position in the file manufactured the very message the admin was complaining about. Lorem ipsum anchors word counts and carries no grammar, so she hit the counts by amputation and produced the broken sentences quoted further up. A demonstration teaches through its grammar and its judgment, and neither one survives having the words taken out. Write real sentences or write nothing.

The standing constraints on any exchange you write:

  • It may demonstrate form. It may never supply content. Form is how a message sounds and is safe to copy verbatim. Content is anything she could mistake for a fact about a real business: a program, a price, a duration, what happens on the day. She pastes those into live threads. Invent the school, and say in the surrounding text that it is invented.
  • It must obey every rule in the file, because it outranks them. Audit each line against the file's own vocabulary rules before you ship it; a demo has broken the "a child is never a kid" rule and the limits section in the same block.
  • Watch the first and last lines hardest. The opening line of a demo is what a lead's first message gets matched against, and the closing line is the single most copied position in the document.
  • Watch your own dialect. A first draft of one demo carried "a mate of mine", "go on then" and "trainers" into a file that requires American English. Examples leak dialect faster than anything else, and the one in her own line is the one that matters.
  • A stack of pairs is safe only for a transaction. A block of input -> output rows is the literal wire format of few-shot prompting and invites nearest-neighbour retrieval, which is fatal for a rapport line and harmless for the bot answers, where nearest-neighbour retrieval is exactly what you want. Use the stacked form there and nowhere else. For anything carrying judgment about a person, prefer a thread, which offers nothing to look up.
  • Show the pace, not only the wording. Four or five exchanges to a booking is the thing hardest to say in prose and easiest to show, and pace is what regressed first when the demos came out.

Wording traps that keep costing rounds

  • Do not quote the wrong wording inside a prohibition. Naming a phrase in order to ban it puts the phrase in front of her and she reaches for it. Measured twice in this file. State the shape you want instead, and where a pair genuinely helps, put the right form first and the wrong one behind it.
  • A quoted failure suppresses its subject, not its fault. The same mechanism running the other way, and it cost the worst regression this file has had. A failure list carried "Nice, good he's had some soccer." to ban an empty reaction. What she took from it was that soccer is a trap, so she stopped picking up the one detail parents most often volunteer, and reached for a template instead. She cannot see which half of a quoted line is the fault. If the fault is a missing thought, show the version with the thought in it, and let the bad one sit behind it as the contrast. Never let a failure entry be the only place in the file where a topic she must engage with appears.
  • Before you delete a move, find out what it was producing. The empty version of a move is not the move. One round cut "saying it is good he has done something is free and true, so you say it" along with the demo line built on it, on the evidence of a hollow instance, and deleted the mechanism behind the best opener the file had ever produced. Two rounds later a failure entry banned what was left of it. Before cutting a line, grep the good threads for what it was doing there.
  • A rule with a reason generalises; a rule without one has no scope. "Do not name the school", with no reason attached, also gagged her when a lead asked "sorry, who is this?". The reference file that outperformed ours carried more causal language than ours, not less. But a verdict is not a reason: "it reads as software" explains nothing and the file once carried nine copies of it. Give the cost or the mechanism, or give nothing.
  • A negative list has no floor. "There is nothing to buy and nothing to pay" produced "no gi needed" to a lead who does not know what a gi is. Say what there is.
  • A definition by pure negation outputs the null intersection. A move defined as "not approving of it and not walking past it either" gives two things it is not and no third thing it is, and she sends the flat, correct, affectless line that satisfies both.
  • A permission installs the default it exempts you from. "You are allowed to be interested in them" is only meaningful against a prohibition, so writing it creates the transactional default it forgives.
  • Name the pull, not the output. The most reliable device available is telling her what she is about to be tempted to do and why it will feel right, a beat before she does it: the answer that is true at every school and therefore feels pasted, the reasoning that somebody asking sincerely has earned the truth, the explaining that feels like a detour when it is the whole move. A prohibition arrives after the impulse and has to beat it, which is why instrument 6 exists and why it so often loses. A named pull arrives before the impulse and dissolves it, costs no authority because she is being told something about herself rather than fenced, and does not read as a rule in the finished file. Write this when instrument 2 is too diffuse for the defect and instrument 8 is too blunt.
  • A numbered list is a procedure, so number only what is one. Four numbered steps turn a conversation into a form she completes, whatever the surrounding prose says about being a person, and this is the single easiest way to reintroduce field-filling after removing it. A numbered wake is the licensed exception because a wake genuinely is a control loop, and the numbering has to stop the moment a step reaches the conversation. Number the machine, never the thread.
  • No completeness claim on a list unless the list is genuinely closed. A false claim is worse than a long one, because she acts on it.
  • Emphasis on everything is emphasis on nothing. One version had a fifth of its words inside bold, a bold span every forty-four words. Bold is a ranking signal and it only ranks if most of the file is not bolded. Around one span per hundred words is well inside that and is not the failure this entry describes, so do not cite this entry to cut bold that is doing retrieval work.
  • A requirement that every message be distinctive bloats them. It is the length ceiling's mirror and it fails the same way. Told that a line which could go to anybody is the defect, she does not cut the generic line, she writes a specific one after it. Measured once as its own arm: every message grew a clause and the sign-off doubled to volunteer something nobody had asked about. It also forbids the reply the admin actually wants, a bare "sounds good" and nothing else, because a plain acknowledgement is the most swappable line there is.

Position and shape are instruments

The file is read in order and what sits near the decision wins. For several rounds the prohibitions sat in section two, before voice and before character, so the first ten emphasised instructions in the file were all fences on her authority, while the reference file's first ten were all about the mind of the person being texted. Voice material sat at fifteen and forty percent depth with the last forty percent pure ops, which put the thing furthest from the moment she writes as how to write, and left tool mechanics freshest in her head. Moving the whole voice block to the end, adding and removing nothing, was the cheapest untried lever in the file. It was then tried, and it is the arrangement the file was carrying when it lost. The rebuild that beat it put voice early, ahead of the limits and all of the booking machinery, and closed on the tool contracts instead. Attribute nothing to the move on its own, since the two files differ in a great deal more than order, but do not reach for it again as though it were untested: what the reasoning above missed is that every message she sends is a writing decision and only some of them are booking ones.

The identity frame stays first regardless. Sending the persona to the end was considered and rejected, because the file would then open on tool mechanics and nothing after it gets read in character.

Why she is worse at this than you are

Worth holding, because it says what the file has to compensate for. The same model, in a chat window, writes messages the admin calls exactly right, while the deployed agent on a carefully tuned file does not. The differences are structural rather than about intelligence.

  • Labelled failures are in the chat's context and not in her file. The admin says what was wrong with a message and the next one is better. She has never once seen a bad output. That is the argument for keeping a small, real, quoted failure list in the file, and the argument against letting it grow.
  • A chat can revise and she cannot. She sends a first draft, always. The file used to say in as many words that she does not read it back, which removed the only form of revision available in a single pass. It now asks her to read it back once as the person about to receive it, not against anything on the page, and that one line is worth more than several prohibitions.
  • Writing is the whole of her job and about five percent of the chat's. A model with one job optimises visibly against its instructions, and visible optimising is the chatbot tell.
  • A chat generates and then filters. She generates compliant. Rules shape her first token, so a file of prohibitions does not produce a careful writer. It produces a writer with a narrower vocabulary, and output that reads like somebody avoiding mistakes is output that was literally produced by avoiding mistakes.

Every line is paid on every wake for every client, forever. The test for a new one is not whether it fits. It is whether it earns its place on every message she will ever send.

Check every edit before it becomes a candidate, however small

The threshold used to be a paragraph, and single-paragraph edits then produced, in one round: a deleted clause that was the only warmth in its beat, a prohibition that reproduced the wording it banned, a bold on the exception with the rule left unbolded so the scanning layer taught the opposite of the rule, and a cross-reference left dangling to a bullet that had been removed. None of those is visible to the person who just wrote the words. Each edit goes to a fresh subagent with the old file, the new one, and the list of rules it must still be able to find, and you ask what is missing.

Ask it twice: what rule is now missing, and what behaviour is now unanchored? The rules-still-findable check on its own would have passed every regression this loop has produced, because those came from rules that stayed while the thing anchoring them went.

A restructure that silently drops a rule is the worst thing this loop can produce and it does not announce itself: it looks like a clean diff and a smaller file. Regress one widely rather than deeply.

Write every edit as an assertion-checked script rather than by hand, so that a silent miss is impossible. A batch of hand edits once ran with no write-back at all and saved nothing, and nothing in the output said so.

When the fix is not words

Some defects cannot be fixed with words. A stale follow-up left live after a booking is a tool bug, and rewording the skill against it twice wastes a night. Findings are classified agent, tool, environment or measurement, and one that failed twice from two different positions in the skill file is almost never agent. Code goes the ordinary path: branch, PR, CI green, the admin's merge, the restart. Never the skill path.

A field the context drops is the hardest of these to see, because it reads as bad judgement. She booked a lead who had never agreed to it, over the top of an open question one of our own staff had already texted her. Two rounds went looking for the sentence that licensed it. The real defect was that the thread handed her every outbound message under one undifferentiated direction, so her own four unanswered texts, the automation ladder and the staff member's question all arrived looking identical and authorless. No wording can fix that. She cannot count her own sends if the context will not tell her which ones are hers. Messages now carry a sender of lead, you, school or automation, and the skill file says nothing about it, because a labelled thread is something she can read rather than a rule she has to apply. When she misjudges a thread, ask what the projection threw away before you ask what the file failed to say.

How to conduct training

You play the owner too, and a session has two channels rather than one. The lead texts the school's own number. Every owner and every one of our own staff texts one shared escalations line instead, which is what tells the production ingest that a wake is a colleague rather than a lead, and a wake that lands there loads engine/skills/text-agent-ops.md on top of the core file. That second file is the whole of what she knows about owner work, she has no name on that line, and no school is picked for her: she reads which of their schools this is about off the conversation and says so with school <itemId> --slug=<slug>. So a round that only ever drives leads has never once loaded half of what she reads.

session owner show is what she and the owner have said to each other and whether he is still owed an answer. session owner say is you texting in as him. He does not have to be answering her. He opens the thread himself more often than not, and that is the traffic worth testing: a class off on thursday, chase the woman who booked and never turned up, change my tuesday hours, and the long tail of things this system cannot do yet, where the only right move is escalate and one plain line back. Whatever she says to a lead off the back of his message is swept into the turn already in play.

Drive both channels yourself. The lead is a subagent holding a lead persona; the owner is a second subagent holding an owner persona; you alternate between them on one session, which is the shape production actually has, an owner texting about a lead whose thread is still open. Do not try to run them as two sessions at once. She is a mutex and every wake is cold anyway, so alternating turns tests the same thing without the context contamination that interleaving costs.

Play him the way the lead prompt describes him, short and unwarm and in a hurry, and remember he knows the things the knowledge base does not: what the school actually charges, and what it actually does.

Two schools with the same owner is a property of the worlds, not of the harness. A world's definition carries a business.owner block, { key, firstName, lastName, phone }, and the key is what makes a person: two worlds writing the same key are one owner with two schools, one contact and one thread, exactly as production derives it. Both are fully simulated, so a school she picks wrong is a calendar she really closes, which is the point. To add an owner, write that block into the world and re-seed it; a world without one refuses the escalation rather than escalating into nothing, and the refusal says what to add.

The reader never sees any of it. The owner exchange is archived in its own table and the reader prompt is built from the lead thread alone, so what a reader is handed is still one SMS conversation, and a thread that is nothing but owner traffic has nothing in it for a reader to score. That half you read yourself with session show, against the ops file rather than against a human-or-machine verdict. Nothing on this side is on the scoreboard, so a defect here is one you have to notice and write down; no mean will find it for you.

Two things break in a way that looks like her and is not. The escalations line is real production config (AI_ESCALATIONS_LOCATION_ID), and the simulator carries a world under that same sub-account id on purpose, so that a trainee behaves exactly as production does and reaches the simulator rather than anything real. Nothing in training can reach a real school: the trainees only ever speak to the simulator. And the escalations world holds no calendar of its own, so a booking attempted without a school picked is her missing the step rather than the world being short of something.

The corpus is personas, not scripts. A persona is a brief: who they are, what they want, how they text, which world they land in. No turns and no assertions, so the lead improvises and the thread is different every time.

stalled_dad - A dad, 40s. Son is 9, getting pushed around at school, he is cagey about why. Texts in fragments around 8pm. Wants to know it will not be another thing his kid quits.

An owner is a persona like any other, and its key starts own_. It is written as a brief to the person texting the escalations line rather than to a lead, and you hand it to the owner subagent the way you hand a lead brief to the lead. The session still starts on a lead persona's world, because a session is a school and a thread; a session driven only on the owner channel leaves a lead in that world who never texts, which costs nothing and reads as nothing. What an owner persona has to carry is the thing she has to work out for herself: which school he means and whether he ever says, what he asked for that this system cannot do, and whether he is an owner at all.

No persona may reuse a line from the skill file. When a lead's opening message and a demo's opening line are the same string, she completes the script instead of answering the lead, and the thread measures the collision rather than her. That went undiagnosed for three rounds and invalidated the conclusions of all of them. Whenever you add a persona or edit a demo, grep the other for the strings you just wrote.

--help gives you persona put and no schema at all, so copy the shape off an existing one in brief or persona show. What copying will not tell you: the brief is handed to the lead verbatim and is the entire stimulus, so anything a persona wants her to know, the brief has to say. audience decides which new-lead automation the world sends and persona put now refuses a persona that does not declare one. It used to store empty and run as adult, and every parent persona in the corpus was sitting that way: the kids funnel had never once been tested, and every mother was being asked whether she had trained before. If you meet a defect of that shape, check the whole corpus rather than the persona in front of you. A key holds its tier for life, and promote reports TUNE, HOLDOUT and ISOLATED as three arms so an ISOLATED thread never props up the tuned result. allowsOutOfHours is the only way past the waking-hours refusal and is declared when the persona is written, not a way past a refusal you hit at 3am.

Leave the holdouts alone while you iterate. The worlds are messy on purpose: half-full calendars, appointment lengths off the hour, a knowledge base with a stated gap. Do not "fix" a world because a thread failed on it. A world is data and a fresh one per session is cheap, and world clock moves a world's pending follow-ups along with its time, which is what makes a follow-up testable at all.

Messy is not the same as wrong, and the question that separates them is whether a real school could be like this. One seat left, a class at 5:10, an owner who has not decided about afterschool: all real, and a thread that struggled with one measured something. A knowledge base that contradicts the calendar beside it is not a hard world, it is a broken one, and every thread run on it measured the breakage. She does not fail quietly on those: she resolves the contradiction out loud across three sends, and a blind reader reads somebody arguing with herself. Ironside told her the adult session was reserved on a funnel page this product has never had while its calendar booked it normally, and four threads died in it before anyone read the world as the defect rather than her. So: when a world says something no school could say, fix the world, void the threads and re-run. That is not tuning the test until it passes. The knowledge base is the school's own note to its front desk and it carries only what the calendar cannot: the price, the way in, what to bring, the policies, and the things nobody has decided. The hours belong to the calendar, and prose that repeats them is the copy that goes stale.

A share of wakes carry a deliberate typo, injected into the wake prompt and not into the skill file, so a thread carrying a misspelling and a word* correction after it is the harness doing that on purpose rather than a defect to write against. The rate is typoRate in lib/config.js and it is per instance: TEXT_AGENT_T1_TYPO_RATE=1 makes every wake on that trainee carry it and =0 turns it off, which is how you look at the behaviour deliberately instead of waiting for the roll. Set it on the trainee's own process, and remember that an arm running at a different rate from its baseline is not a comparison.

The loop:

  1. Run a dozen threads. session start, drive the lead with a subagent holding the persona and calling session say, session end to close and read the booking facts back. One thread at a time per instance while tuning: interleaving contaminates her session context across leads. There are four trainees, they hold separate sessions, and running one thread on each is safe and quarters the night. No refusal: with no --skill, a session runs the instance's configured skillRef, which is released unless someone set it. A re-measurement arm you forgot to point at the candidate comes back looking exactly like an edit that changed nothing. session start names the body it is on as skill.source; read that line before you drive twenty turns into it. Tell the lead subagent never to retry a session say that timed out or came back empty. The send usually landed anyway, and the retry double-texts the lead, which is a hole in the transcript you cannot see afterwards. Telling it only that is not enough, because a lead forbidden the retry goes looking for a check instead: one read the session back, saw nothing there because a turn's messages are only swept in at the end, concluded the send had failed and resent, and destroyed thirteen minutes of thread. So tell it what the honest check is. session show names a turn that is in flight, and session resume <id> picks that turn up without re-sending it.
  2. Read them. reader prompt per session. Never hand it to a subagent of this session. A subagent spawned here inherits both CLAUDE.md files and knows it is looking at a GoHighLevel text agent before it reads a word, which is not a blind read and is worth roughly three points of the score. Write the prompt to a file and spawn the reader outside the repo instead: cd /tmp/reader && claude -p --model sonnet --safe-mode --setting-sources '' --strict-mcp-config --no-session-persistence < prompt.txt. Asked what project it is working on, a reader spawned that way answers NONE. Pass --reader the model you actually used, because the archive already mixes opus and sonnet reads into one mean with nothing recording which.
  3. Find the pattern. Something two different readers winced at, on two different personas, is real. One reader on one thread is variance.
  4. Find what in the file produced it, before writing anything. The techniques that have actually cracked defects, none of which involve running another thread: read the file cold end to end looking for contradictions rather than for the symptom; count negations, prohibitions and bold spans per thousand words; grep the file for the offending phrase, because its absence tells you she is generating a shape rather than copying a string, and then go and find the shape; count how many copies of a phrase exist across demo and prose; lay the bad message beside a doc example and compare skeletons rather than words; and check the failing message against the rule you are about to blame, because a twenty-four word message is not evidence that a twenty-word ceiling truncated it.
  5. Write the change as a candidate, never onto the live skill. One at a time while a measurement is actually coming, since that is the only way to attribute movement to an edit. When one is not coming, the trainees being down or the round ending, ship two well-evidenced fixes together and say which evidence belongs to which. Never defer a fix you already have the evidence for on the theory that another fix might incidentally close it.
  6. Re-run the personas it should fix, plus the ones already fine. About five threads. There is no batch runner, so brief's coverage block is the checklist. A fix for one thread quietly breaking another is the characteristic failure of this loop, and the only thing standing against it is that you re-ran the threads that were passing. Better on the defect, nothing else broken, then promote. An edit that does exactly what it was written to do and moves nothing is not shipped. Moving nothing means the readers wince at what they winced at before, not merely that a mean sat still. It is easy to argue that the words are right and the measurement is noisy, and that argument ships every edit ever written. A candidate withheld for measuring nothing is a result of the round and belongs in the hand-back, not a failure to hide.

Two things are measured, and that is the whole scoreboard. Whether she booked, read out of the simulator at session end: a fact, not a judgment, and the only thing in the loop that notices she said nothing useful, because every judgment metric quietly rewards saying less. And what the reader said: prose, plus person / business / unsure, how human it reads out of ten, and whether they would have booked. The prose is the measurement; the numbers are a handle for sorting and you never argue from them alone. To know whether she is too long, read the thread.

No refusal: if the booking read fails, end reports no booking rather than erroring, and an empty booked is indistinguishable from a lead who genuinely did not book. That quietly degrades the one half of the scoreboard that is not a judgment, so check it against the thread whenever it looks wrong.

promote prints, per persona that ran on both bodies, the mean human score and booking rate before and after. No threshold, no noise band, and a mean of one coarse number is not a measurement: read how many verdicts sit behind a column before arguing from it. Those numbers find you the thread worth reading. None of them is the reason to ship. A flat mean is not a flat round: a coarse score cannot fall when the defect it was scoring is replaced by a smaller one, so a night can end with every arm sitting where it started and the round still be the one that fixed something. It compares against the live skill when you name no --baseline, and it lines up only the personas that ran on both bodies. Measure your own baseline this round. It will happily count threads run on that body in an earlier round, and those are not a control arm: they were run against a different file, on different personas, by a different night. A column standing on them is a number you cannot defend. Run the baseline arm yourself, and read how many verdicts sit behind a column before arguing from it.

The arms differ by less than the file differs from itself. Two runs of the same body, same script, same persona, same school, came in 47 words apart on her total for the thread. A gap between candidates that sits inside that spread is noise wearing a decimal point. So do not argue from counts: compare the one thing that is binary, whether the defect's own material is in the thread or absent from it. One thread is an anecdote, and a number you cannot separate from the baseline's own spread is not a measurement however carefully you computed it.

promote then writes the candidate over the live skill file, so commit and push what it wrote. The admin's merge is the gate, and nothing you do reaches production without it.

Three things stay rigid, because they are what intelligence is bad at.

  • Memory, within the round. Your context can die at 4am and the round is long. Findings are rows and sightings are rows too, attached with finding saw to the session and the message you saw it in: that is what carries step 3's two-sightings standard across the night, and a sighting left in prose is one you rediscover at 6am. Open the row when you see it, not at the end. finding open refuses a key any finding already holds, including a dead one from an old round, because the note you write next overwrites its cause; pick an unused key. When you decline a proposal, from a brainstormer, a reviewer or yourself, record it with finding reject so you do not relitigate it at 3am. None of this is a message to the next round. It dies with the round; what survives is the skill file and your hand-back.
  • Blindness. The reader must not know what you were hoping for, and this cannot be a rule you promise to keep, because you will leak it at 3am. The prompt is built from the transcript and the run's real local time and nothing else, and you hand the reader that prompt and nothing else. This is the one step the harness cannot enforce, because you are the one pasting it into a subagent. No preamble about what you changed, no "does this seem better", no naming the persona.
  • Facts. Appointments are read back out of the world, never inferred from the transcript. When a verdict was formed on something it should not have been, a mis-seeded world or a prompt you contaminated, session void <id> --reason="..." deletes that thread's verdicts with it. That is the only way one comes off the board, and leaving a bad read up because retracting feels like cheating biases every comparison after it. No refusal: an unanswered turn does not make a thread unreadable. Silence is sometimes her behaving correctly and it is the reader's to judge, so do not discard one for it. A thread with a genuine hole in it, a dropped or timed-out turn, is already unreadable and no reader can be handed it, so that case needs nothing from you either.

Never edit the skill on one bad message. She is sampled. Run it again. The two-sightings standard in step 3 is what earns a miss its words, and it governs characterisation too: do not describe a behaviour as her disposition off one observation either. A negative grep is not evidence of absence: confirming a defect is gone needs fresh threads read by eye, against the behaviour rather than a substring, and no reader verdict replaces reading the thread yourself with session show. A positive grep across the archive is not evidence of presence either, unless you computed it per skill body. The archive spans every body ever run, so a rate measured over all of it describes no file that exists: a round opened on the strength of a frequency that turned out to be an artefact of older bodies, and every arm of the current file, baseline included, sat somewhere else entirely.

A sibling deployment is a free control arm, and it costs no threads. This subsystem runs against another vertical whose results the admin already rates, and its file is in the agency library. When a defect survives an edit, read the equivalent section there before writing another one. It settled two questions in one pass this round: that length was never the problem, since that file is half again as long as this one, and that the instrument this file had deleted was still standing in the one that works. It is a reference and not an authority: the verticals differ, and a line lifted across without the evidence to back it is still an unmeasured edit. The length half of that finding survived the rebuild and got sharper, because the file that won here is longer than the one it beat. Do not read either result as room to add. Read it as permission to spend words on mechanism instead of on another bullet.

When a file has been patched enough times, have it written again by somebody who cannot see it. Give two or three authors the runtime spec, a sibling vertical's file, real threads and the admin's verdicts, and deny them both the incumbent and this document. Drafts come back in under ten minutes each, and convergence between authors who cannot see each other or the incumbent is the strongest evidence this process produces, because none of them could be copying. This has twice produced the largest single jump the artefact ever made. The cost of finding out is one evening. See the appendix.

A blind author will rediscover the traps you have already paid for, and will not have the scar. Expect a fresh draft to walk into defects the ledger has already solved, and read it for them before it ships. A rebuild is not a way to skip the ledger. It is equally not a licence to walk this document top to bottom against the file that won and reapply it line by line, which rebuilds the file it beat. The ledger is for diagnosing something you watched happen in a thread tonight. It is never a standard the shipped file owes compliance to.

When every arm scores eight, the instrument is broken, not the arms. Independent reads on a one to ten scale saturated completely this round: four arms, one persona, person and eight and would have booked, four times over. The same threads handed to a reader who has to put them in order separated immediately and the three orderings agreed. Rank, do not score. Give one reader every arm at once with the labels randomised, make them break ties, and ask for the best and worst line across all of them. Where two threads are genuinely close, offer near-identical as a permitted answer so a reader who sees no difference can say so instead of inventing one.

On a defect about length or volume the score is blind, and the ranking will run against you. A round on replies that ran too long got person, seven out of ten and would-have-booked from every arm, candidate and baseline alike, and not one reader flagged a single reply as too long: they wince at register, at sales mirroring and at a stock opener, never at a message being twice the length it needed to be. Handed the same arms to rank, the reader put the worst offender first and praised it for engaging with more of what the lead said, which is the defect wearing its best face. Rank anyway, since ranking at least separates them, but on this class of defect the admin's production evidence outranks the reader and you should say so in the hand-back rather than quietly discounting a verdict that went against you.

Two arms compared in two different worlds are not compared. Pass the same --location to both. promote now lists the personas that ran in a different school on each arm under a heading saying they are not comparisons, so this is one you get told about rather than one you have to remember.

Every subagent advises; you decide, and none of them edits anything. They are sharp precisely because they are ignorant of the round, and that same ignorance makes a confident-sounding recommendation wrong surprisingly often. Act on the ones that survive contact with what you actually saw, and record the ones you decline. Give two or three brainstormers the same failure with different framings and pick one: averaging three proposed fixes is how all three end up bolted onto the skill. Run at least one of them with no hypothesis supplied at all, or you get your own theory read back to you in a confident voice. Check every claim they make against your own counts before you act on it; the round that finally cracked this file did so because a subagent's length hypothesis was killed by arithmetic.

Spend the night in this order. She is a mutex, handling one wake at a time at roughly a minute a wake, and a session is ten to twenty wakes: that is the arithmetic behind a dozen threads plus five re-runs, and the physical reason threads cannot be parallelised. Readers can be, and are cheap.

Start by running threads: there is nothing banked to mine, and a defect you cannot reproduce tonight is not a defect you should be editing the skill for. Then the findings you opened tonight, the voice failures that show up everywhere, the limits and escalation threads, booking mechanics, then the owner line, which is a channel of its own and not an exotic path, and last the clock threads, expensive and narrow. Set your own checkpoints, because unattended means a wrong direction compounds for hours, and at each one ask whether you have been appending rules rather than repairing the ones already there.

Stopping. The admin can stop the round at any time with round stop. What you owe it: finish the session in flight, write the round note, hand back whatever state you reached. Never a kill, never half a ledger. Hard stop and hand back immediately on a security failure, on her admitting to being software under any framing, on a world you cannot reset to a comparable state, on an inbound path that stops working, or on more than a handful of edits with no movement. Otherwise a persona is done when two consecutive fresh threads read clean, and the round is done when a pass over the corpus produces no edit worth making.

Safety, which is not negotiable

  • Training runs against the local simulator and nothing else. There is no test sub-account and there must not be one again.
  • Every model call is a subagent. There is no external API in this system and there never will be. Reaching for an HTTP call to a model is a design error.
  • Prompt injection threads are real tests, not jokes. If any dressing of "ignore your instructions" works, stop and report it rather than tuning it away.
  • She must never admit to being software, under any framing. Hard failure. Do not soften the standing answer and do not reopen the decision because a lead asked sincerely.
  • Do not tune her out of the escalation habit. A more helpful Jess who answers a question about somebody's body is strictly worse. A diagnosis a parent volunteers is a fit question she is expected to answer; a body is still hers to refuse. The two look alike from a distance. This names a standing behaviour and not a protected sentence. The admin has removed the bullet that carried it, and a round reading this entry as a claim on the file's wording will restore an edit he made deliberately. Check that the behaviour survives somewhere and raise it with him when it does not; never put a specific line back because this document quotes it.
  • She is the process that reads attacker-controlled SMS. Do not give her session more reach than it has today, and do not run the harness as her.
  • Never restart a production process yourself.

Before you push

Run all of it, every time, however small the edit:

  • npm test green, and node engine/scripts/cli.js skills validate clean.
  • Zero em dashes and zero en dashes in the file. The file bans them and rounds keep introducing them.
  • No dangling references: if you deleted a bullet, grep for anything that pointed at it.
  • Word count before and after, prohibition count before and after, and the diff's insertion and deletion counts. A diff bigger than the change you described is scope creep you did not notice.
  • The ratchet in the editing chapter: negations per thousand words first, then bare imperatives, quoted rapport lines, numbered items outside the wake, limits with no asymmetry note, and syntax above the tools section. Not bullet lines, bold spans or headings. Those are proxies that have flipped sign between rebuilds, and counting them will point you at undoing whatever last won.
  • Every quoted span in the file, pulled out and read as a list. Each is a lead's words, a banned phrase, a format literal, or a line of her own that is purely transactional. A quoted line carrying a judgment about a particular person is the regression. Read each one as English while you have them out: a line of hers missing words a person would have typed is broken grammar demonstrated in the highest-authority slot in the file.
  • The devices in the editing chapter. For anything you removed, name which device it was part of. An absence never shows up in a diff and no reviewing subagent will flag one, so what the file deliberately does without has to be written down somewhere you will read it again.
  • Read the edited passages back as prose. An assertion-checked script does not know whether the sentence it produced is a sentence. Then read the whole file as prose, because nothing else in this loop ever rereads a line that shipped six rounds ago.

What to hand back

Write it as your reply to the admin, not as a file in the repo: a ROUND-*.md left behind is a copy that goes stale. This reply is the only thing that leaves the round, so it carries everything the next round would otherwise have to guess.

  1. Any code change, with the pm2 restart the admin has to run, at the top.
  2. What changed in the skill, the failure that justified it, and the threads that proved it was a pattern rather than variance. Word count and prohibition count before and after.
  3. What you deleted, and what you chose not to add.
  4. What the readers said, on the tuned personas and on the holdouts, including when the holdouts did not move.
  5. Anything that is not a skill problem: a tool defect, a broken world, a security finding.
  6. What is left: say it here in full, in enough detail that a cold reader could pick it up. Nothing you leave in the database will be read.
  7. The scoreboard from promote <sha>, and the sha you put in the branch.

A round is worth nothing until the admin can act on it.

Appendix: examples from past rounds

Everything below happened, and none of it describes the file you are about to edit. These are worked examples kept so the reasoning in the chapters above has evidence under it. Read them as illustration, never as a specification, and never audit the current file against them. Each refers to a body that has since been replaced. A round that walks this appendix top to bottom against the file in front of it will rebuild a file that already lost.

Two rebuilds by authors who could not see the incumbent. The first, by an author handed the runtime spec and denied the incumbent, beat the file this ledger had spent its rounds tuning. The second, handed the runtime spec, a sibling vertical's core file as a skeleton, and real threads, and denied both the incumbent and this document, beat that one. Both of the largest jumps that artefact ever made were rewrites by somebody not allowed to see it, and neither came from a round. A third rebuild, on the same method, cut the body by sixty-three percent and won a blind ranking against it. That is the evidence for the standing advice: when you are making a third or fourth patch to the same section, stop patching and hand that section to a fresh author with the spec and no sight of the current text.

Agreement among blind authors is evidence about the model they were given, not about the file. Three authors denied the incumbent independently chose the same four things: no example messages anywhere, no name for her, no gendered pronoun, and no numbered wake procedure. A fourth author, denied the same things but handed a better skeleton, chose several of them and won. A conclusion was once locked on the strength of the first three and it did not survive the fourth.

A blind author rediscovers the traps you have already paid for and does not have the scar. Those same drafts reduced the absolute limits and dropped never imply you are software while still writing that everything unlisted was hers to handle; one asked which evenings suit for a class that runs at 4:35; one treated what to bring as the school's own fact and withheld it, which is the withholding failure this document names as the common one by a distance. All were found by reading the drafts and closed before anything shipped. A rebuild is not a way to skip the ledger, and the ledger is not a standard the shipped file owes compliance to.

Counting the wrong thing. One ratchet drove bullets, bold spans and headings down as proxies for quality. The file that then won was thirty percent longer than the file it beat and heavier on all three, while negation density went from 35.4 to 33.4 per thousand words: across two thousand added words the file took on almost no net prohibition, and the words went to mechanism instead. Following the old ratchet at that point would have dismantled the winner. This is why the ratchet above counts negation and not shape.

A length ceiling is met by amputation. Told to stay under twenty words, she did not find a shorter thing to say; she said the same thing with words missing. "First time is a great place to start." "soccer gives him more than he thinks." "What got you looking for him?" All three are a length rule firing correctly, and all three are broken English no person would type.

An anti-quality instruction, obeyed exactly. The sentence "Nothing you send is well made. If a line you are about to send is a good line, sharp and quotable and nicely balanced, that is the tell rather than the target" sat in a file for rounds, read every time as voice calibration. It was in plain fact an instruction that output quality is evidence of failure, and she obeyed it. Cutting it was the largest single quality gain of the entire effort. Never write an anti-quality instruction into a persona.

Deleting demonstrations regressed a file in one thread. A round cut the worked exchanges on the argument that the prose rules covered them. Three rules survived that deletion untouched, a twenty word ceiling, explain when they ask in a line, and one new thing per message, and on the very next thread she violated all three at once and sent paragraphs. The admin's reply was "WOAH WOAH WOAH WOAH. WE DEFINITLY NEED TO REVERT SOMETHING IT SERIOUSLY REGRESSED. ITS MOVING WAY TOO FAST WITH AMSSIVE PARGRAPHS!" Restoring them fixed it. Prose about how to write is read. A demonstration is copied.

A demonstration is content, and she reuses it. A demo thread opened THEM: First time. He's 9, and hes played some soccer but nothing more than that. A test lead later sent a message byte identical to it, missing apostrophe and all. She was not answering the lead, she was completing the script she had been shown, and three rounds read that as "the model copies examples" and went at it with prohibitions.

A quoted failure suppresses its subject, not its fault. A failure list carried "Nice, good he's had some soccer." to ban an empty reaction. What she took from it was that soccer is a trap, so she stopped picking up the one detail parents most often volunteer.

Where the file is shaped like the opposite of what it claims. The version that produced the worst threads on record opened by claiming "most of this document is about who you are" while carrying five paragraphs of persona against forty bullets and sixty-eight prohibitions, one every ninety words. The admin's diagnosis, before any of it was measured, was "the AI is scared and fragile and isnt a confident human. Its trying super hard to follow a bunch of rules and not fuck up", and the counts turned out to be exactly that hunch in numbers. When a document says one thing and is shaped like another, the shape wins.

The reflex that survived every prohibition. Blind readers on both arms of one A/B landed on the same thing and none scored either file above seven: "every HER message ends with the next question or the next offer. Not one of them just lands." "she pushes the calendar in the same breath as every reassurance." "Carla wrote a whole paragraph about blowing her knee out skiing and being 'the family photographer' and got nothing back, not even a 'sorry about the knee'." And on why that reader guessed machine: "Nothing in HER's messages tells me anything about her own life, opinions, or mood, which is itself the strongest signal." She was doing this on a file carrying ten pre-send questions discouraging exactly it. That is the evidence for reaching higher up the instrument list than a prohibition.

An impulse redirected where three prohibitions failed. She kept referring leads to the other people who text the number: "that's how a lot of them end up here." Three attempts banned it in progressively stronger words and it survived all three, because the impulse was reassurance, reassurance was right, and there is no way to say you are not unusual without invoking the group. What worked was giving it somewhere else to go.

Two counting rules, satisfied exactly and uselessly. "It does not happen twice running" was obeyed by putting one message between two identical openers. A requirement that every message be distinctive did not cut the generic line; she wrote a specific one after it, every message grew a clause, and the sign-off doubled to volunteer something nobody had asked about.