Three Ways to Read a Domain Model Your Team Already Agreed On

Somebody asks how one part of your product actually behaves.

That question has three places to go, and each of them has a cost.

• A Colleague Who Knows: accurate, and paid for with the attention of the person most likely to be building the thing that depends on the answer. Asked often enough, they become a lookup service.
• The Written Documentation: available immediately, and carrying no indication of which parts still hold after everything that has changed since it was written. Most readers check the code afterwards anyway, which makes the document a detour.
• An AI Reading the Sources: immediate, fluent, and now the default. It is also the one worth examining, because a project like mine has to justify itself against it.

An assistant can read both sources. The code is the physical source of truth about what runs, the PRDs and the issues are the business source of truth about what was intended, and an assistant handles the vocabulary gap between them well enough.

Where the two disagree, and they disagree often, an assistant has to choose a side. It does that without telling you, and the answer sounds equally sure either way. The disagreement is usually the most useful thing you could have learned, and it does not survive the answer.

There is a smaller cost too. An answer assembled out of source files reads as an account of source files, which suits the engineer who was going to open them and leaves a product manager no better off.

None of that is about answer quality. It is that the answer settles something on your behalf and does not say so. Braid is my attempt at a fourth option, and this post is the reading end of it. The first post covers how the model gets built.

The Fourth Option

The fourth option is to put the same question to a reviewed model instead of to the raw sources. Where the code and the intent disagreed, a person decided which one the model would say, and that decision sits on the node with the evidence behind it and the name of whoever made it. The choice still gets made. It just gets made once, in the open, before anybody asks.

Three ways in, all reading the same reviewed model.

1. Search That Ranks by Meaning

The query is how a chat message becomes a reply. Two of the things it returns are called Run Turn and Conversation Turn Lifecycle, and neither of them contains a single word from the question. They came back because search over the model ranks by meaning as well as by name, so a concept can be found by what it is rather than by what somebody happened to call it.

Documentation search usually fails on a page that exists, because the reader did not guess the author's word for it.

The same graph is also served over a read-only MCP endpoint, which exchanges each caller's own token so somebody reads it as themselves from their own client. That is the one path here aimed squarely at an engineer.

2. Ask

Every node an answer draws on carries the lines it was drawn from, so each claim in the answer has a specific place it came from, and that place was vouched for by a person before the question was ever asked.

The run also reports its own accounting, covering the searches it ran, how much of the result set it read, and how much of that it went on to cite. Prose gives no such account of itself.

3. Documents That Say When They Went Stale

A document in Braid is written from material projected off the model, for a stated reason and a stated reader. The projection is a function of the model, never a copy, so the same subject can be written more than one way and each one knows when the model has moved underneath it.

That is one subsystem written twice. The reference is for looking things up and carries a live slice of the model inside it. The tutorial closes each chapter with a question the reader answers and is marked on.

Both read Out of date, because a proposal landed and moved the model under them. Neither is wrong yet, and neither claims to be right. That is the one thing a page in Notion never tells you, which is whether to trust it.

An Answer Shaped Like What It Is Saying

The reader is a person, and some content is understood faster in one form than another.

• A comparison of several implementations is read as a table.
• A sequence of steps is read as a diagram.
• A claim is read alongside the sources it rests on.

Markdown has one shape, the paragraph. Ask a model for markdown and everything it knows is flattened into that shape, leaving the reader to rebuild the structure on the way in. That rebuilding is work the answer could have done for them.

A Braid run therefore renders instead of writing a page, and every rendered piece declares its own kind. The kinds available to it include a passage of the answer, a comparison, a slice of the model, a diagram, a finding, the sources behind a claim, and an account of what the run searched for. The run selects the form that suits what it is saying, and how that form appears belongs to the interface.

One answer, three shapes. Prose where prose is right, a matrix where the content is a comparison, and every concept the answer names carried as a reference to the node it came from.

Because a rendered piece says what it is and never where it sits, one sequence can be a scrolling answer on one surface and a page on another, drawn by the same components and re-authored for neither.

How It Compares

Four places a question can go. The first row is what this post is about.

	Braid	AI over the Sources	Team Docs	Ask an Engineer
Settles a Source Disagreement	Yes, a Person Did, on the Record	Silently, if at All	Only One Side of It	Yes, and Unrecorded
A Human Vouched for It	Yes, Node by Node	No	Once, Long Ago	Yes
A Non-Engineer Can Act on It	Yes	No, Code-Facing	Yes	Yes
Shaped for a Reader	Yes, per Piece	No, Prose About Code	Yes	Yes
Traceable to the Source	Yes, Per Claim	Partly, Links to Files	Rarely	If You Ask
Says When It Is Stale	Yes, on Its Own Face	Regenerates Blind	No	n/a
Answers Without Costing Anyone Their Focus	Yes	Yes	Yes	No

AI over the Sources covers the chat window with your repository attached and the wiki that writes itself from it, such as DeepWiki or Karpathy's llm-wiki run as a skill. They differ in packaging, not in what they read, which is why they share a column. Pointed at an unfamiliar repository to find your way around, they beat Braid outright.

The trade appears once an answer has to be relied on. Every one of these options resolves the gap between what the code does and what the product was meant to do, because an answer cannot be given without resolving it. Three of them resolve it invisibly, in a model's weights or in a colleague's head or in a document nobody has revisited. Braid moves that resolution earlier, into the review that builds the model, where a person makes it and the reasoning stays attached to the node afterwards.

What Is And Is Not There Yet

The first post lists what is missing from the model itself. These are the three that bite at the reading end, one for each surface above.

• Ranking by Meaning Is Opt-In: it needs an embedding endpoint pointed at the workspace. Without one the request is not an error, it quietly falls back to matching the text, and a question phrased in the reader's words finds nothing again.
• One Ask Skill: Ask reaches for a single question-answering skill, which today is the built-in one. A workspace can add its own build steps, but a second flavour of Ask is read and not yet offered.
• A Stale Document Waits for You: a document says when the model has moved past it and then does nothing about it. Catching it up is a button somebody has to press, so the honesty is automatic and the freshness is not.

Closing

A shared model is only worth building if reading it beats reading the code, and for the first months of this project that was not obviously true. The reading end is what makes the rest pay off.

If your team keeps sending the same questions to the same person, that is the problem this is aimed at. Give it a run and open an issue with the question it should have answered and did not.

• Repository: github.com/mroops0111/braid
• The First Post: Turn a Codebase into a Domain Model Your Team Signs Off On
• The Worked Example: examples/conciergent