The Specification Is Not a Document - The Phoenix Architecture<br>Imagine joining a software project a few years from now.<br>It is a large, mature system. It has thousands of business rules, years of operational experience, regulatory obligations, performance constraints, strange edge cases, customer commitments, and architectural decisions made by people who no longer work there.<br>You ask the obvious question.<br>"Where's the specification?"<br>Someone gives you access to it.<br>There is no SPEC.md. No 900-page requirements document. No canonical YAML file. No giant prompt that somebody feeds to an agent. There is not even a directory you can browse and reasonably call the specification.<br>So you ask how you are supposed to understand the system.<br>The answer is another question:<br>"What do you want to know?"<br>What is this system for?<br>Who depends on it, and what promises does it make to them?<br>Why does checkout retry a failed authorization three times?<br>Which parts of the system are affected by European data residency requirements?<br>What did production teach us in the last twelve months?<br>Which architectural decisions still depend on assumptions that are no longer true?<br>Each question produces a different view of the same underlying body of knowledge.<br>It is tempting to imagine that somewhere behind this interface there must still be a canonical specification: some master representation that contains the whole system in its definitive form.<br>But that may be the wrong assumption too. The durable knowledge of a system might not have one natural representation at all. Some of it may be formal, some executable, some observational, some textual. What matters is that these pieces can be identified, related, queried, and traced back to their sources.<br>I don’t think there is a single thing underneath all of this that a person could sensibly open and inspect from beginning to end.<br>You don’t read it because there is no useful order in which to read it.<br>That may turn out to be one of the more important changes in how we think about software in the generative era.<br>Documents impose order. Filesystems impose hierarchy.<br>When we say that a specification should be human-readable, we usually mean that a human should be able to inspect it and understand what it says. That is obviously desirable. But we have traditionally achieved readability by imposing a particular presentation on the underlying knowledge.<br>A document has an order. Its author decides that one idea should come before another. A source file contains an ordered sequence of text. A codebase is more complicated: its files are normally organized into directories, packages, modules, repositories, and dependency structures.<br>Those structures are useful, but they impose a primary organization on information that often does not have one.<br>Consider a mundane rule in a payments system: a failed authorization can be retried up to three times within a particular interval.<br>Where does that fact belong?<br>It belongs to payments, but also to reliability. It may be constrained by the behavior of an external processor. A production incident may explain why the number is three. An architecture decision may explain why the retry happens asynchronously. An SLO constrains how long the process can take. A compliance requirement may prohibit retrying in some circumstances. An evaluation should reject future implementations that violate the rule.<br>A directory tree still makes us choose where something lives. Everything else becomes a reference, a duplicate, a search result, or a fact somebody is expected to know how to find.<br>Documents have the same problem. If I write an architecture document, I have to decide whether retries belong under Payments, Reliability, External Dependencies, or Failure Handling. Cross-references help, but I am still flattening a multidimensional set of relationships into an authored sequence.<br>The retry rule is connected to a requirement, an implementation, an evaluation, an external dependency, an incident, a decision, and the reason for that decision. Those relationships are themselves part of what we know.<br>Today, the person trying to understand the system reconstructs that graph.<br>Perhaps we should store the graph instead.<br>We already know how to stop reading the source of truth<br>There is old precedent for this move.<br>In 1970, Edgar F. Codd published A Relational Model of Data for Large Shared Data Banks. One of the important ideas behind the relational model was independence from physical representation. Users should be able to reason about data without knowing the machine-level structure used to store it.<br>That idea now feels mundane because it won so completely.<br>Suppose I tell you I have a database containing twenty million customer records. You would not ask me to send you its storage files so you could read them. You might inspect its schema because you need to understand the vocabulary and relationships available to you, but then you query the contents.<br>Show me customers who haven't ordered...