A runbook has an audience of one.

A runbook works while the person reading it is the person who wrote it, because that reader silently repairs every gap as they go. They know the step that says restart the workers means the two on the old host as well. They know the ordering constraint that never made it onto the page. They supply the missing context invisibly, and because it is invisible, the document appears to work for everybody.

Give the same runbook to the second person on the team at eleven at night. The gaps are now load bearing. Every ambiguity resolves into a decision that reader is not equipped to make and does not know they are making. The document has not changed at all. Its audience has.

This is not a documentation quality problem and it does not get better by writing more. Prose about a system drifts away from the system the moment either one changes, and nothing enforces the connection between them. A script has the opposite property. When a script drifts, the release fails, loudly, at a moment when somebody is watching.

The thing a runbook cannot be

It cannot be reviewed in any meaningful sense. You can proofread it. You cannot diff it against what actually ran last time, you cannot test it, and you cannot tell from reading it whether it still matches the system it describes. Approving a runbook is an act of faith dressed as an act of governance.

A shell script that has grown over two years is executable. It is not reviewable, and the gap between those two words is the entire subject of this company.

Reviewable means that a competent colleague can read the file once, form an accurate expectation of what is about to happen, and point at the step they disagree with. That is a stronger requirement than correctness. A correct file nobody can hold in their head buys you nothing on the night it matters, because the person watching it run has no model of what it should be doing and therefore cannot tell when it stops doing it.

Three things that quietly destroy it

• Indirection. Every hop into another file costs the reader their place. After five hops they stop following and start assuming, and an assumption is exactly what the review was supposed to catch.
• Configuration that changes behaviour. When the same file does different things depending on a value the reader cannot see from the file, reading the file no longer tells them what will happen. It tells them what might.
• Steps that are not in the file. One manual step in the middle is enough. The reader now has to know it exists, know when it happens, and know whether they are the one doing it.

The tooling exists to make those three expensive rather than convenient. That is a narrow ambition, and we would rather state it narrowly than dress it up as a platform.

We are only willing to publish the five properties because most of them are mechanical. A property that depends on somebody remembering it is a property that survives until the first bad week.

• An unreadable plan. A team of four reads the plan output and still cannot say what the release will do. That would mean the format is the problem rather than the runbook, and the format is ours.
• Release files that fork. If they become as long and as branched as the runbooks they replaced, we have moved the mess rather than removed it, and moving a mess into a repository makes it look governed without making it better.
• A gate that is a formality. Second readers who approve without reading are worse than no gate at all, because the approval manufactures a record of a review that did not happen.

We will publish which of these we hit. That commitment costs nothing to make today, which is precisely why it is being made today rather than after there is something to lose by keeping it.

• No shipped product, no release, no public repository and no package on any registry.
• No customers, no pilots, no letters of intent and no named users.
• No revenue, no outside investment, no grant and no accelerator.
• No benchmark, no uptime figure and no measured reduction in anybody's incident rate.
• No security audit, no penetration test and no independent review of any kind.
• No team page implying a headcount we do not have, and no advisers listed who have not agreed to it.

Some of these will change. When one does it will change here first, with the thing that happened described in the same plain terms as the absence it replaced.