Skip to main content
In short: you want to know where the agent’s answers come from, and why you should trust them. Before it answers, the agent reads a set of written guides that cover the product, from your account and lending to options and fees. Each guide must describe what the code does today, and the guides are versioned and tested like code, because a wrong guide makes the agent give wrong advice. The agent reads a set of written guides before it answers you. They are the only description of this system it has. If a guide is wrong, the agent confidently tells somebody to do something that cannot work. That is why the guides are versioned and tested like code.

​
What they cover

Each guide covers one area, and together they cover the product. The areas are below; every guide is listed separately, generated from the directory. A hand-written summary of a growing set drifts as soon as a guide lands that fits no row here. That happened when bracket and grid orders arrived.

​
The rule that keeps them honest

A guide describes what the code does today, never what it will do or used to do. Every claim should be checkable against the catalogue, a test, or a run. When the code changes, the guide changes in the same commit or it starts lying.
That rule has already been broken once, expensively.One guide said “there is no operation that waits for a price, and you must not look for one”. That was true when it was written, and the guide kept saying it after the feature shipped. An agent reading it talked somebody out of the exact thing they were asking for.A negative claim is the dangerous kind, because nothing fails when it goes stale.
The second rule is about editing: a guide has one editor at a time, and a change lands in one commit. Do not edit a guide somebody else is editing. If a change touches three guides, commit them together. A reader who gets one guide from your commit and another from somebody else’s gets a contradiction.

​
What to change when

Search first. grep -rl "loan.close" skills/ costs nothing and finds the ones you forgot.

​
A guide may only name a tool that exists

A tool that spends is also withheld while the agent is discussing a request. A guide that tells the agent to call one while it is still working out what somebody wants describes a call that will be refused. → What the agent can call

​
Under the hood

How retrieval works, and how to write for it.

​
Short facts sit beside the prose

Each guide has a companion file of short facts: the same knowledge, in the shortest form that is still true. The prose is long because it carries the reasons, and the sentences that tell an agent how to say a thing do not compress into claims at all. But a question like “can I borrow gold here” is answered by one line, and answering it from prose alone costs the 542-word section that line sits in. So facts are indexed beside the prose rather than instead of it. Retrieval leads with facts and follows with the two best sections. That is cheaper than five sections and finds more, because a fact is a small document dense in the terms somebody actually searches for. Two properties:
  • One fact, one entry. Grouping a section’s facts into one row would return them the way prose is returned: all of a section, to answer one question, which is the cost this removes.
  • The heading links a fact to its section, and the build checks that link. A fact names the section it came from, and the section supplies the line range. So a fact always cites the prose behind it. A heading that no longer exists fails the build, so no fact can outlive its source.
Facts are the one thing here that is written rather than derived. Everything else is reconciled from a file by content hash. Extracting facts is a model’s job, and doing it at startup would make the corpus non-deterministic, slow, and different in every process. So they are extracted once, reviewed by a person, and committed.

​
Writing for retrieval

The index searches sections, not whole files. Three rankings are combined: one that stems English words, one that keeps identifiers intact, and one that weights by how rare a term is. Name the subject in the heading and in the first line of the body. The ranking cannot find a section that never says what it is about. Measured on this corpus: the best answer to “what is an approval gate” was a section headed “When a run stops and asks”, which does not contain the word “approval” anywhere in it. Keep sections short. The ranking divides by length, so a two-line answer beats an essay that mentions the subject in passing, but only if those two lines are their own section. Write identifiers exactly: arm_schedule, limit_price, loan.close. The literal ranking exists so somebody typing a name finds it. An English stemmer mangles those into something a search for the exact name no longer matches.

​
The index rebuilds itself

The index is a cache, and the files win on every startup. Unchanged sections are not rewritten, and sections no longer on disk are removed, in one transaction.
  • Restart the tool server after editing a guide and the change is live. There is nothing to migrate.
  • If the database will not answer, the process reads the files instead. The database is never the source of truth.
  • Where the tool server runs from a built image, guides are baked into it, so an edit there needs a rebuild rather than a restart. The startup line that names how many sections were indexed shows the change took effect.

​
Before you commit

  • Search for the thing you changed across every guide. Did you get all of them?
  • Restart the server and ask the question a person would ask, in their words.
  • If a section you expected did not come back, the heading is the problem, not the ranking.