2.4 Lifecycles and Runbooks

You know what to do when the disk fills up, when two branches conflict, when an incident pages you at 2 a.m. You know it so well you barely notice you know it. The agent knows none of it. Out of the box it knows how to commit to Git, of course; what it does not know is the life cycle of your engineered environment. The disk fills, and here is what to do when the disk fills — that instruction will never be in the agent's context unless you put it there. It has no operating context, no sense of "how we do things around here," and the more of that judgment your operation runs on unwritten, the more helpless the agent is the moment the healthy path ends. So a governed environment for real work writes the knowledge down — as lifecycles, and as the runbooks that ride on top of them. This chapter is about capturing the operational judgment you carry in your head so an agent can act on it.

2.4.1 Lifecycles first, then the failure map

Start with the lifecycles, because everything else hangs off them. A lifecycle is the correct operation of one recurring activity: how a bug report moves from filed to fixed, how a feature moves from design to shipped. Write the healthy path first. Then, from each node on that path, map the failure states — the ways this step can go wrong — and for each failure, the action to take. Think of it as a grid: every node crossed with every symptom, and in each cell, what to do.

The formal name for building that grid is failure mode and effects analysis. You enumerate what can go wrong, then the consequence of each, and then — the part people skip — how to get out of it again. You know how to get out. If two branches conflict, you read both sides, work out what each was trying to accomplish, and reconcile them. If the disk fills, you find the fat part of the system — the cache, usually — and wipe it. The agent knows none of this. It does not know where to find each commit's intent during a merge conflict, and it does not know where your system's fat points are — and it may, just maybe, decide the fix for a full disk is rm -rf /. You think I am joking. Read Twitter; agents do it all the time. So you coach it: where the hot points are, and, in every failure path, what is not allowed. Encode the prohibition as a mechanism at the right level where you can — a Git hook, an agent hook — and where you cannot, at least tell the agent plainly.

A footnote on the pink elephant. Telling an agent not to do something raises an honest question: does naming the forbidden act make it more likely? A human cannot help picturing a pink elephant once told not to — though without the telling, the thought would never have come. I don't know about you, but when I read the law — or the police blotter — it gives me all kinds of wicked ideas I would never have thought of on my own. In my own system the naming helped, but only when I named the escape alongside the sin. My orchestrator kept reaching for a destructive Git command to bail out of a stuck merge — the one that resets the branch and silently discards the changes already applied — twice losing committed work that way. A bare prohibition ("never abort the merge") would have left it stuck with nowhere to go. What worked was pairing the forbidden command with the sanctioned one that clears the stuck state without dropping the applied work, so the rule read "not that lever, this one." Name the sin alone and you may plant the temptation; name the sin and the way out and you replace it.

2.4.2 Runbooks: split the deterministic from the judgment

Once the healthy path and the failure map are written, the thing you hand the agent is a runbook (or playbook): the steps to take, whether recovering from a failure or working a fresh ticket. The one discipline that makes a runbook work is to split it into two kinds of step — the deterministic and the judgment-laden — because the two are governed completely differently. Figure 2.4-1 fences the one judgment step between two deterministic ends.

Learn more about this governance mechanism: runbook.

The deterministic parts get tools. Anything that has a single correct outcome should be an executable script the agent runs, not a procedure it improvises. Leave it to improvisation and it will get it right most of the time — and you will wish you had automated it the one time it does not.

Determinizing a step buys you more than a reliable outcome — it buys you a trace. When a step improvises, its reasoning is smoke: gone the moment it finishes, impossible to inspect or compare. Pin the step to an executable procedure and the reasoning becomes a record — the inputs it read, the branch it took, the value it produced — written down in a fixed shape. That record has two consumers, and between them they are the reason to capture the trace and not merely the outcome. The first is the next turn of the loop: last run's trace is this run's input, so the agent starts from what was already reasoned instead of re-deriving it, and the loop converges instead of wandering. The second is a second checker that reads the trace itself — a reviewer, human or agent, that never watched the step run but can now audit how it reached its answer and flag a trace that took a path it should not have. A judgment step gives you only its verdict; a determinized step gives you the verdict and the reasoning behind it, and the reasoning is the part a checker can hold to account.

The judgment parts: the roughest algorithm that still fits

The judgment parts get the roughest algorithm that still fits. For a well-constrained decision, write the algorithm down and let the agent do the glue. For an open-ended one — a cyber threat hunt, where the premise is that the attacker did something you never anticipated — do not over-constrain: give heuristics and strategies to explore, and stop there. Remember that you are conditioning a probability distribution: steer it down the wrong path and it will never reach the place you wanted. So if you do not know how to do the thing, do not write as though you did — give hints. If you truly do not know, say "solve this open-endedly," and accept the trade: the looser the guidance, the more tokens the agent spends, and the less likely it is to land.

When a judgment step is really a measurement, give it a rubric. You cannot write a checker for "is this painting good" or "is this student essay good," but you can operationalize it: how are the topic sentences, how is the technique, are there grammatical errors, are there blotches from bad storage? The agent will not deliver a final verdict on taste, but with a rubric it gives feedback good enough to act on.

The strongest form of this is the pre-canned brief. When an orchestrator agent has to hand work to a sub-agent, you do not want it inventing, each time, how to explain the task. You want a template it adapts — the work already articulated in writing. The companion repository leans on exactly this: every dispatch is composed from a template that pre-places the required instructions, and a brief-linter checks the template is intact before the agent launches. Templates constrain how work is described to agents, which is the whole business of this book, applied to the act of delegation itself.

Learn more about this governance mechanism: brief-linting.

The split has a mechanical form once you write runbooks at scale. Type every step as one of three kinds, and let the type decide how the step is governed. A deterministic step is runnable: it carries the exact tool line to run. The judgment steps divide by whether an agent can take them. A judgment-automatable step carries a pre-canned brief the orchestrator dispatches to a strong model, the missing middle between "run this" and "you decide." A judgment-irreducible step carries the words to surface to the person, because the call must stay theirs. Table 2.4-1 gives the three kinds and what each must carry. Typing the step makes the shape checkable: a tool line on a judgment step, or a dispatched brief on a runnable one, is a contradiction a linter catches before the runbook ships. The failure map from the last section joins the same way, each symptom routed to its runbook by its class rather than its exact error text, so a fresh failure that rhymes with a known one still finds the way out.

Step back from the taxonomy and the chapter is one instruction wearing three shapes. A lifecycle writes down the healthy path and the way out of each failure. A runbook rides on top and splits every step in two: the deterministic part earns a tool, the judgment-laden part earns the roughest algorithm that still fits. The pre-canned brief hands that split to the next agent intact. What used to live only in your head — how the work is done here, and what must never be done — becomes something the environment holds and can enforce. Delegate the operation, not just the code, and it stops depending on who happens to be awake at 2 a.m.

Brief. The written instructions handed to an agent for a task: what to do, where, and how "done" is judged; the artifact the pre-canned template produces.