# =============================================================================
# Published - From a Novel Helper to an IT Oracle (verbatim)
# =============================================================================
# An article authored by Cedric Ancellin, first published on this site.
# Text is preserved as written (including original wording and any typos).
# Governed by ../LAWS. Verbatim files are exempt from the em-dash rule.
#
# Added on 2026-11-01.
# =============================================================================


title: "From a Novel Helper to an IT Oracle"
author: "Cedric Ancellin"
published: "2026-11-01"
platform: "zc8.com"
linkedin_url: ""   # set once cross-posted to LinkedIn
cover_image: "/assets/articles/from_a_novel_helper_to_an_it_oracle.jpg"
topics: ["knowledge base", "oracle", "YAML", "AI coding agents", "hallucination", "context window", "RAG", "AI agents", "ontology", "decision records"]

summary: >
  How Cedric's oracle came about: a YAML knowledge base built so an AI could
  keep track of a fantasy novel's characters, reveals and translations once
  the book outgrew the context window, after a year of attempts, including
  local models, that hallucinated or missed facts. The same failure appeared
  in software when an AI quietly replaced a recorded session design, so he
  applied the oracle to documenting code, coding, product design, a legal
  case file and managing agents. The article gives the eight rules to build
  one (laws, indexes, small files, one home per fact, perspectives, record as
  you go, implicit gaps, git), a decision file example, and the four ways the
  existing tools fall short.

body: |
  The knowledge base I now use to run software projects with AI came out of writing a novel.

  I am writing a fantasy novel. The world is complex, with several societies, a system of magic, factions, and a large cast whose relationships change from chapter to chapter. The story is built on reveals, and the reader has to learn certain things at a precise moment and not one chapter earlier.

  I wanted an AI helper that could keep track of the characters, the story, what had been revealed to the reader and what was still hidden, and which details had been planted for a payoff ten chapters later. I also wanted to translate the book with that context, because a good translation needs to know things the sentence does not say, such as whether a character is speaking to a superior or to a friend, or whether the reader already knows a secret at that point.

  For over a year I tried to build an AI knowledge base for the book, including with local models running on Ollama. Each approach worked while the book was small. Every time I tested it after the book grew beyond the context window, it either hallucinated or failed to retrieve some of the information it needed. In a novel both failures are fatal, because an invented detail contradicts an earlier chapter and a missed detail can spoil a reveal.

  What finally worked was organizing the content rather than looking for a smarter model. I moved the book into YAML files, split by perspective, with files for the characters, relationships, locations, events and chapters. For each chapter I recorded what the reader knows at that point, and what the chapter reveals, conceals and plants. The same fact can be reached from several directions, but it is written in only one place.

  I called it the oracle, because it holds the answers. When I have a question about the book, I do not ask the AI what it remembers. I ask what the oracle says, and it answers only from what is written there.

  It had a cost. The oracle became more voluminous than the book itself, and keeping it up to date slowed down my writing. But it was able to extract everything, and it did not hallucinate. As a novel helper, it was a success.

  Then I realized I had the exact same problem at work.

  When you build software with AI, the first problem you hit is hallucination and limited context. The AI forgets things, makes wrong associations, and inside one project it can branch two different ways without you noticing.

  I once had it build a session system in a personal project where authentication went through Supabase but the session itself stayed local, for security. It did that correctly. As the project grew, AI quietly added a Supabase session on its own, because that is what is commonly done and it assumed that is what I used. Everything still worked, so even a mid-level engineer would not have caught it, and the security reason for keeping the session local was quietly gone.

  It was the same failure as a spoiled reveal in the novel. A decision made early in the project was lost once the project outgrew the context, and the AI replaced it with the most plausible guess.

  So I applied the oracle to IT. I used it first to document code, then to assist coding, where the AI builds against the oracle instead of guessing from the code and checks a recorded decision before it writes. I used it to design products before a line of code exists, the way I described in [The Junior Developer Is Gone](https://zc8.com/published/the_junior_developer_is_gone), with the ontology, the schema and the use cases written first. I even extended it to a legal oracle for a case file. It worked every time. My own site, zc8.com, is itself an oracle, built for AI agents to read.

  It became even more useful once I started creating and managing agents. One agent is manageable, but as a project grows you end up with many, each with its own role, scope and rules, and they depend on each other. When you reprogram one, you need to know what every other agent expects from it, because a change to one often requires a change to others. An agent that is handed something it no longer expects does not crash. It carries on with a wrong assumption, exactly like the Supabase session. With an oracle, each agent is documented, with what it does, what it reads and writes, and which agents depend on it, so before I change one I can see every agent that must change with it. Without that record, the more agents you run, the more certain you are to make a costly mistake.

  Right now I am pretty pleased with it, and I am using it for more and more of my work. This is how you can make one for your own project.

  You do not need to build any software. You need a folder, git, and an AI agent that can read and write files, such as Claude Code, Codex or Cursor. The files are YAML, and the method is a handful of rules.

  YAML is the infrastructure that makes the oracle work. It is the plain text format IT already uses for configuration files everywhere, and its structure is explicit, so a source or a status is a field rather than a sentence someone may have forgotten to write. It allows comments and reads naturally, so a person can correct a file in the middle of a conversation. It is only text, so git shows every change line by line. Links between files use the $ref convention borrowed from JSON Schema and OpenAPI, which turns the files into a graph the AI can follow. People and AI read the same files in the same way.

  **1. Start with the laws.** Create a LAWS file that the AI reads before anything else. The first law, and the most important one, is that nothing is fabricated. The AI never guesses, speculates or invents anything to fill a gap. It works only from facts recorded in the oracle, each with its source, and every entry carries a status, decided, proposed or open, so that what is not known is marked open rather than filled in. In my oracles the law says that an empty field is correct and an invented one is a violation. Only you can promote something to decided.

  **2. Give it one entry point and complete indexes.** An overview file at the root says what the oracle is and in what order to read it, and every folder has its own overview listing every file in it. The AI walks down the indexes, so it knows it has seen everything instead of hoping a search found it.

  **3. Keep the files small.** Each file covers one subject and stays around 250 lines, never more than 400, except raw evidence. The AI reads the index and then the one file it needs, in full, so its context stays small even when the oracle is huge.

  **4. Give each fact one home.** A fact is written once, and every other file points to it with a $ref. Because nothing is copied, nothing can contradict itself.

  **5. Organize by several perspectives.** A software project might have folders for the schema, use cases, architecture, decisions, integrations and agents. Each perspective is a different way into the same facts, never a copy of them.

  **6. Record as you go.** Every working session is logged in a sessions folder, close to verbatim, and every decision gets its own file with its reason. The AI writes into the oracle in the same turn the knowledge appears, rather than at the end. A conversation disappears when it ends, and the oracle does not. Before closing a session, and during a long one, run a consistency check on the oracle, so that what was recorded in a hurry does not leave a broken reference, an unregistered file or a contradiction behind.

  **7. Write down what you do not know.** Each file ends with an "implicit" list of its known gaps, which keeps the AI from filling them with guesses.

  **8. Put it in git and check it.** Git keeps the history, and a small script checks that every reference points to a real file and that every file is listed in an index.

  This is what the decision file for the Supabase session looks like, modeled on a real one:

  ```yaml
  # decisions/D-037-sessions-are-ours
  decision:
    id: D-037
    title: "Sessions are our own: the identity provider only verifies who a person is"
    date: "2026-01-30"
    status: decided
    source: "sessions/2026-01-30-admin-login, entry r31"
    trigger: >
      Cedric: "Supabase verifies who the user is, nothing more. We never
      use its sessions. We mint our own."
    reason: >
      Security. The session must not live with the identity provider.
    decided:
      the_identity_provider_verifies_only: >
        Supabase verifies the login once, returns who the person is, and
        its session is discarded on the spot. Nothing of it is stored,
        refreshed or sent to the browser.
      we_mint_the_session: >
        A signed token in an HttpOnly cookie naming a session row, so a
        session can be ended server-side and dies on inactivity.
    applies_to:
      - $ref: ../architecture/authentication
      - $ref: ../schema/session
    implicit:
      - "The session lifetimes are open. The build uses 7 days and 8 hours idle, which are the assistant's numbers, not a decision."
  ```

  With this file in the oracle, the agent that is about to add a Supabase session reads D-037 first and leaves the session where it is.

  To start, open your agent in an empty folder next to your code, give it these rules, add your own, and ask it to write the laws and the overview first. Put the reading order in the agent's instruction file, CLAUDE.md or AGENTS.md, so that every session begins by reading the laws and the overview. Then work as you normally would and have it record as you go. Once the oracle grows, you can serve it over MCP so your whole team and their agents read the same one, but a folder on your laptop is enough to begin.

  If this sounds like something an existing tool should already do, I thought so too, but none of them gave me all of this at once, and I hit walls with all of them. Each fails in one of four ways.

  Some retrieve what is similar rather than what is correct. RAG and vector databases such as Pinecone, pgvector or Chroma cut the text into arbitrary chunks, never tell you whether the retrieval was complete, and lag behind the source after every edit.

  Some have no rules. Wikis such as Obsidian and Notion let anyone write anything, so nothing stops a duplicate, a contradiction or an invention. AI memory such as ChatGPT memory, Claude memory, Letta or Mem0 lets an LLM decide what to keep, with no source and no review, so a wrong memory persists, or replaces a right one, without anyone noticing. GraphRAG has the same problem at build time, since an LLM extracts the whole graph and nobody reviews what it wrote.

  Some are too heavy for a person to fix in the middle of a conversation. Knowledge graphs and the semantic web keep the knowledge behind a query language and heavy tooling, so correcting a fact is an engineering task rather than a sentence in a chat.

  And some are too small, or stop working when the corpus grows. Architecture Decision Records cover design decisions and nothing else. Agent context files such as CLAUDE.md and Cursor rules degrade after a few hundred lines. A 1M-token window is expensive on every question, loses facts in the middle, and fails the day the corpus outgrows it, as my book did. The agent harness itself, Claude Code, Codex or Cursor, owns the loop but not the record, so reasoning is lost when the context is compacted and rules that cut across the project get decided differently from one part of a task to the next. That is exactly what happened with my Supabase session, and it is why the harness needs the oracle.

  An oracle is bigger than its source, because everything in it is explicit and sourced, and working with it is slower, since it takes many small reads and writes. If your project fits comfortably in a context window, you do not need one. When it does not fit, and you need the AI to know everything and invent nothing, this is the only approach that has held up for me, from a novel to a production system. The pieces all existed before, and what is new is how they are assembled, with each one designed around how a language model reads.

  In [Growing Engineering from Startup to Series B](https://zc8.com/published/growing_engineering_from_startup_to_series_b), I told you to build an AI friendly knowledge base that your engineers and their agents live off. This is it.

  The rule I now follow is to never let the AI work from a context it can escape.


transcription: "As written by Cedric Ancellin, first published here 2026-11-01."