← Back to my work
Field notes · Building AI systems

Every build starts with a diagram

Almost everything I build is under an NDA. I can talk about the method, but not about the systems it produced. So here is the one project that is mine, with its diagrams, to show how I build.

It isn’t a toy. For two years I’ve been in a Telegram correspondence with a friend, an experienced data scientist: about 50,000 messages, most of them on software development, AI engineering, context architecture and building AI agents. The conversation is deep, and it’s spontaneous: an idea comes up in a thread about something else, gets its answer, and sinks. A correspondence like that holds a lot of ideas you could turn into insights, or into sources for the content you publish. The question I set myself was how to package all of that experience into a reproducible agent that turns it into ready content.

Whether OpenClaw does it, Hermes does it, or you build it my way makes no difference. If you need a reproducible result, you need an architecture.

I build with AI. That doesn’t mean I write a prompt and the program assembles itself. I build by a playbook, and every build starts with a diagram.

  1. Define the intent. Iterate with the AI until the intent is one page: why this system should exist and what result it owes. It’s step 10 of my adoption playbook, and it’s here again because the build starts from it. For this project the intent fits in two sentences. Every message in the archive gets a place in a discussion or a short exchange, with a link to the original. The wiki that grows out of them keeps the topics, the discussions under each topic and their sources, so that I can draw insights and content from it.

  2. Draw the diagram. In a new chat, iterate on the architecture as a diagram. It doesn’t have to be detailed, and it doesn’t answer every architectural question, only the most important ones. The rule is that you understand it at 100%: after reading it, how every node talks to every other node is completely clear to you. Where you can’t say that, the diagram isn’t finished. It’s the one document in the build that’s written for you, and it’s the one you come back to when the code and your understanding disagree.

Archive messages become reviewed, source-linked wiki records.
Accepted results are saved before their messages count as processed.
  1. Find the unknown unknowns. Stay in the same conversation. You know what you know. You know what you don’t know, and those were the questions you asked. But there are things you don’t know you don’t know, and some of them matter most for the project. So ask the AI exactly that: what haven’t I asked about? The AI names them, you decide which ones belong on the diagram, and you iterate until the questions stop coming. On this project the answers became the layers under the main diagram: where a discussion begins and ends, how topics change without re-reading the archive, how to know which messages are already done, how a reader finds a discussion and its sources, and how this wiki sits inside my main one.

Context extends around the selected dates to form a whole discussion.
A continuation keeps its discussion ID; a new episode gets a linked record.
A message coverage ledger distinguishes context reads from accepted results.
Reading for context does not complete a message’s own processing.
  1. Write the spec. From the intent and the diagram, the AI writes the specification: the diagram executed in detail, for the AI. Everything the diagram leaves open gets decided here.

  2. Review the spec diagonally. You read it, but you don’t need to understand it in full. The diagram you read at 100%. The spec you skim, for the places where it departs from the diagram.

  3. Start a new session with the three documents attached: the intent, the diagram and the spec. One shot can be enough to take a project like this from zero to one. The models are good enough for that now.

What the diagrams decided

Three decisions on these diagrams aren’t about Telegram at all. They’re the ones I’d take to any project that turns a stream of messages into knowledge, and none of them came from the code. They came out of the diagram conversation, and the code is written to them.

The unit isn’t a line. Messages are grouped into semantic units, discussions and short exchanges. A discussion is one question, one task or one situation, and its boundaries come from meaning and reply links. A day’s end is not a boundary, and neither is the end of a batch. An episode is a list of message IDs, so every conclusion in the wiki leads back to the messages it came from, with the author kept. The root agent runs the pass: it hands out unparsed messages with their context, links the episodes that belong together across chats and dates, and keeps the account of what’s done. An agent with the parsing skill finds the discussions. Another agent checks each one against the sources: boundaries, completeness, authorship, conclusions and quotes. Programs do the exporting and the writing.

The topics are an ontology, and one agent owns it. Each discussion is matched against a shared dictionary of topics: an existing topic, or a new one with an explanation of how it differs from its neighbours. Only the root agent changes the dictionary. It creates, refines, merges and splits topics, and updates the pages and links that are affected. Renaming a topic never re-reads the archive. Splitting one re-examines only the discussions linked to it.

Renaming, merging and splitting a shared topic catalog.
Catalog changes preserve links and revisit only the discussions they affect.

The wiki lives inside the second brain, behind a door. The Telegram wiki is a separate subsystem inside my main wiki. A topic page shows the overview, the positions people took, the discussions by date and the open questions, and leads to the originals. Coverage is tracked by message: every ID points to where it’s represented, and the remainder points to the reason it’s still out. A message read for context doesn’t count as done. The main assistant answers ordinary questions from the main wiki and goes to the Telegram wiki only when I ask for it.

A topic links to a discussion and its original source messages.
The original message retains its author, date, full text and provenance.
Ordinary questions and Telegram requests follow separate paths in one wiki.
Telegram enters the answer when the user asks to consult it.

That’s the whole method. The intent and the diagram you understand completely. The spec you skim. The code the model writes, and it’s checked against all three. Which agent runs the result is a detail. The architecture is what makes it come out the same way twice.