Specs Live in Incidents
4 min read

›Contents
Ask an operationally complex business for its documentation and you will receive something: a procedures binder, a policy wiki, an ERP training deck. Ask the people who actually run the process whether that documentation is the process, and you will get the laugh of someone who has worked a month-end.
The written procedures describe the process as designed. The business runs on the process as evolved, and the difference between the two is the most valuable knowledge the company owns. Nobody wrote down the evolution. It happened one incident at a time.
Where the real spec accumulates#
Consider how an operational rule is actually born. A payment posts twice. Someone spends a bad week finding it. The fix becomes a habit: always check the settlement file against the bank feed before posting, because the processor double-sends on holiday weekends. That sentence is a specification: precise, conditional, load-bearing. And its permanent home is one person's memory, plus maybe a note in a ticket that closed four years ago.
Multiply by every escalation, every auditor finding, every "oh, for that franchisee you have to calculate it the old way," every workaround with a person's name attached to it. An operating business is a sediment of resolved incidents, and the sediment is the spec. The procedures binder is the geology textbook; the incidents are the actual rock.
So "just document your processes" fails at every company that tries it as a project. Documentation drives toward the general case, and the general case is the part everyone already knows. The value is in the exceptions, which get recorded, if at all, in the places nobody thinks of as documentation: postmortem threads, month-end checklists photocopied until the edges blurred, the follow-up email that starts "going forward, let's make sure we..."
Why this suddenly matters more#
For decades, keeping the spec in people's heads was survivable, because the people executed the process too. Judgment and execution lived in the same skull; the spec traveled with the work.1
Agents break that arrangement. The moment machine labor executes your process, the process must be stated. An agent doing accounts-payable work will do exactly what the documented process says, which, as your operators will tell you through the laughter, is not the process. Every undocumented exception becomes a fault line: the agent posts the double-sent settlement file, because the sentence that would have prevented it lives in Marie's head, and nobody asked Marie.
The asymmetry cuts one way: the general case (the part your documentation covers) is the part models already know. Ledgers, three-way match, standard close procedures: all of it is in public training data, described a thousand ways. What no model knows, what no competitor knows, is your sediment. The exceptions are the only part of your process that is genuinely, permanently yours. Which means the exceptions are not a documentation problem. They are the moat, currently stored in a medium (human memory) with high attrition and no backup.
Extraction is fieldwork, not prompting#
The tempting shortcut is to point a model at the wiki and the ticket archive and ask it to "extract the process." This produces a beautifully formatted version of the geology textbook. The rock does not surface, because the rock was never written where the model can see it.
Getting the real spec out is closer to fieldwork. It looks like sitting with the operator during an actual close and writing down what they check before they trust a number. It looks like walking the exception queue and asking, for each item, "what rule decided this?", then asking where that rule is written, and hearing "it isn't." Or reading five years of postmortems and turning each one into a testable sentence:2 given these conditions, the correct behavior is this, and here is how you can tell.
The output of that work is not prose. It is a set of statements precise enough that a machine's work can be graded against them. That gradeability is the whole difference between documentation and specification: documentation tells a human roughly what to do; a specification lets you determine whether work (anyone's work, any machine's work) was done right.
The Operator's Move#
Run an exception audit on one process; it costs nothing but attention. Pull the last ninety days of one queue: billing disputes, manual journal entries, claims escalations, whatever your business's version is. For each exception, write down the rule that resolved it, one sentence, in the form "when X, the correct handling is Y because Z." Then note where that rule currently lives: a document, a system, or a person's head. Two things come out of this. You get a count (what share of your real operating logic exists only in skulls), and you get the start of the extraction, in the form (condition, correct behavior, reason) that any future automation can be graded against. When the exercise gets hard, notice which person makes it easy. That is your master weaver. The continuity of your operation currently depends on their tenure.
References#
-
Michael Polanyi, The Tacit Dimension (University of Chicago Press, 1966). ↩
-
Betsy Beyer, Chris Jones, Jennifer Petoff, and Niall Richard Murphy, eds., Site Reliability Engineering (O'Reilly, 2016), ch. 15, "Postmortem Culture: Learning from Failure." ↩