The Field Manual

Preface

Book One of this pair is an argument. It is meant to be read once, in order, and it ends where the argument has to end, at the operator. This book is not an argument. It is the thing I reach for when something on my machine is already wrong and I need to know which kind of wrong.

Here is where it came from. A year of operating a fleet of coding agents left behind a dossier of 154 failures, written down as they happened. When I sorted them by the signal in front of me rather than the subsystem behind it, 147 of the 154 reduced to eleven recurring classes of trouble, each caught by one discipline. Those eleven classes are the chapters. The case for living this way is Book One's whole job and is not repeated here; each chapter cites it once where it must and moves on.

So let me be straight about how this book expects to be used, because it is close to the opposite of the last one. Almost nobody will read this book, and I mean that as a design constraint, not modesty. You will look something up in it, on a bad afternoon, with something already broken, and the book is built for exactly that entry: a random page, mid-incident, five minutes. The triage index on the next page is the on-ramp. It turns the thing on your screen into a chapter number, it is the only part of the book meant to be memorized, and it names the one line of itself to memorize. Land on a wrong row and the chapter's first paragraphs will name the right one and send you there. You can read this front to back; the index exists so you never have to.

Before you go looking, know what is not here, so you do not spend an hour hunting for a chapter that does not exist. Seven of the 154 incidents do not reduce to the eleven classes, and this manual refuses them openly rather than filing them where nobody would look. The classes catch quiet misreports, and two kinds of lesson fall outside that: a failure that announces itself, loudly and accurately, needs no diagnostic class, and a lesson that is construction technique rather than diagnosis belongs in a different kind of book. I will also tell you how the seven were found, because it is this book's own medicine. Three were refused in the original sort, on that stated criterion: E023, E028, and E144. The other four, E005, E014, E015, and E029, were caught afterward, meeting the same criterion unapplied. The sorting of the dossier failed in one of the ways the dossier warns about, and it was caught the way this book says things get caught, by checking the work against the claim. One more absence is not a refusal at all: the afterword names a class the dossier never witnessed.

Two more limits, in the same register Book One used for its own. Nothing in the dossier ever paged a customer. The blast radius of every entry caps at one person's portfolio, so the manual's calibration for user-facing stakes is extrapolated, not earned; if your failures reach paying users, treat my sense of proportion as a floor, not a fit. And the dossier has no denominators. It records what failed, never how often the same operation succeeded, so when chapter 11 argues that ceremony should scale with blast radius, its proportionality arguments rest on judgment rather than frequency data. I can tell you what a wrong assumption cost. I cannot tell you how often the assumption holds.

Under all three sits the limit every self-collected record carries: the dossier holds what I noticed. The quietest failures, the ones that never announce themselves and never surface, have zero entries by construction. And every entry has the same witness. I noticed these failures, I wrote them down, and I sorted them into the classes I now claim they prove. Read accordingly.

Book One closed its preface with a promise and a warning. This book's version is one instruction, about age. Every chapter carries a ledger of receipts, most of them dated, and the dates are the point: the entries are perishable, the disciplines are not, and these pages are supposed to go visibly stale. When a ledger line names a tool that no longer exists, that is not the book failing; that is the book demonstrating its own chapter on stale records with its own pages. Trust the rules longer than the receipts, and when a receipt ages out, replace it with one of yours.

That is everything this preface owes you. Nothing here needs to be begun. The next bad afternoon will pick the page, and the index will take you the rest of the way.