Key takeaways
- Every automation we run is supposed to have a written entry answering the same seven questions, and the rule is that a new one does not ship until it does. That rule was enforced by remembering, which means it was not enforced.
- So we drew the whole fleet as a map. Each written entry becomes a route: when it fires, what it does, whether a human gates it, where the work lands.
- Each route is joined to the live scheduled job by the file path the entry already names. Anything running that no entry claims appears under its own heading instead of not appearing.
- The shipping debt is on the screen now. That is the entire point, and it is uncomfortable in exactly the way it should be.
- Two design choices carried the whole thing: the join key has to be something the writer would have typed anyway, and a vague entry becomes a vague row that somebody then has to read.
We have a standing rule here that nobody argued with and nobody followed. Build an automation, write its entry in the team playbook before you call the work done. Seven questions, same seven every time. Where it runs. What triggers it. What it does. What a human still does. Where its memory lives. How you can tell it ran or failed. What will bite you.
Good rule. Enforced entirely by somebody remembering at the end of a long build, which is the weakest enforcement mechanism that exists.
An invisible gap is not a gap anybody fixes
The problem with a rule like that is not that people break it. It is that breaking it produces nothing. No error, no missing file, no red mark. An automation with no entry runs exactly as well as one with an entry, so the only person who ever notices is the one trying to understand the system six months later, and by then there are eleven of them.
So we stopped trying to enforce it and made it visible instead. The playbook already existed as a written document. Something now reads that document, parses every entry into a shape, and draws it.
The current read is two hundred and nine entries across eleven chapters. Eighty one of them name a script file somewhere in their text.
That last number is the interesting one, because it is the join.
The join key has to be something you would have typed anyway
A map of written entries is a map of intentions. To be worth anything it has to connect to what is actually running on the machine, and that connection needs a key both sides already carry.
We could have added an identifier field to every entry. We did not, because a field that exists only to make a tool work is a field people forget to fill in, and then you are back where you started.
Instead the key is the file path. When somebody writes the entry for an automation, they say where it lives, and saying where it lives means naming the script. That sentence was always going to be written. So the map pulls every path out of the entry, finds the scheduled job running that same file, and pins the two together.
Now the row shows the written intention and the live reality side by side. When it last ran. When it runs next. Whether it is paused. Whether it is failing.
And the subtraction is where the value is. Take every scheduled job, remove the ones some entry has claimed, and what is left is the list of things running in this business that nobody wrote down. They get a heading of their own that says exactly that.
Two things we got wrong first
Worth saying out loud, because both are the kind of bug that quietly produces a confident wrong answer.
The first was the numbering. Entries are numbered, and when an automation gets slotted in beside an existing one it takes a letter, so there is a twenty eight and a twenty eight b. The first version of the parser expected a plain number. It skipped every lettered entry without complaint, and those automations then showed up on the map as undocumented. Documented work, reported as debt, by a tool built to measure debt.
The second was subtler. An entry sometimes mentions another automation by name in its warnings section, as in do not run this while that one is running. The parser was treating any mention as ownership, so a task got marked documented because a completely different entry had warned about it. Now only the name and the location count as a claim. A mention in the warnings is a reference, not documentation.
There is a third thing that is not a bug but matters just as much. The playbook is a dated document, not a live feed. So the map prints how old it is in days, right at the top, because the worst version of this tool is one that quietly presents a month old snapshot as the truth about right now.
The entry is what somebody reads
Once a written entry becomes a row on a screen, the writing stops being paperwork. A vague line about running nightly and handling content produces a row that tells a reader nothing, and now it is a row they have to scroll past.
That changed how the entries get written more than any instruction could have. Name the file. Say the actual trigger. Say plainly whether a human has to approve something. Those three sentences are the difference between a map and a wall of text.
What this means for your business
You do not need a map. You probably need the subtraction.
Write down every automated thing running in your business. Every scheduled report, every sequence, every integration somebody set up once. Then go and look at what is actually running and cross off the ones on your list. Whatever is left is the part of your operation that only exists in one person's head.
That is the list that hurts when that person is on holiday, and it is the only list worth building first. For most marketing automation San Jose businesses run, it is longer than anybody expects and about a third of it turns out to be something nobody wants any more.
Want this built for you
We build automation you can see all at once, plus the websites and funnels feeding it. Start at optechsol.llc.