field notes
Short notes from real engineering work: one decision, one incident, one reversal at a time. Each one names the shape of the problem, the tension that made it hard, the decision, and what it cost. The internals stay out — the codename is the hint.
If you have five minutes rather than an afternoon: the three case studies condense this material to one problem, one decision and what the decision cost. The notes below are the record those studies cite — and the projects the codenames belong to are on the front page.
A system that helps write its own documentation produces confident prose about things it does not know. The failure is not a lie. It is a guess that is well formed and sits in a document that is otherwise correct, which is the hardest kind…
A tree that grows module by module accumulates a particular kind of artifact: the thing that is named, is plausible, and is not used. This one had a module for a shared topology layer that nothing else depended on. Nothing was deployed from…
Two registers had grown to cover the same ground. One was meant to hold only claims that cut across the whole estate; over time it had acquired role definitions and storage rules that were true of exactly one system, because that was where…
Identifiers get allocated by whoever is holding the pen, drawn from a numeric space that seemed large when it was chosen. Two registers feeding the same system had each grown entries in the same block of numbers, for unrelated subjects, so…
A record field that can hold only true or false cannot hold "nobody has decided this". Written as a yes-or-no, an open question reads as a no, and a register full of noes looks like a system that considered everything and declined, which is…
Turning a document into something a build can verify gives it a machine reader, and a machine reader is a new place to be wrong. The claims were prose — which components connect to which, what has to sit between them, the chains those…
Prose about a system has no way to notice that the system moved. The sentence written confidently one month and false the next looks identical, and the reader has no instrument except the age of the file, which measures when somebody last…
A document that lists every decision a system rests on can only be trusted if it is complete, and a complete register written by hand costs a person's attention in proportion to how much has been decided. That cost is paid exactly when…
Code review looks at what changed. A second kind of review looks at how it changed, across a stretch of the mainline, and asks whether the record can be read by somebody who was not there. That review found four classes of drift and no…
The registration form is where a platform's promises become a customer's problem, so it is the wrong place for a single combined checkbox. The change that landed separated the agreements from the marketing permission, linked each required…
A product that ships in two languages has a defect class no reviewer catches by reading. A missing translation looks exactly like a finished screen, in the language the reviewer happens to speak. Multiply that by dozens of files and several…
A single-page application served from several mount points has an ordering problem that never appears in development. The shell needs to know which mount it is under before it can resolve a relative asset reference, and the usual answer is…
A staff editor was built from a design document while the server served something else: a different address for the same resource, a different encoding for the same geometry, values arriving as text rather than numbers, and a single…
The board a kitchen works from is the least forgiving screen in the product. It has to show, per ticket, what was ordered, in what quantity, what was added or removed, what the customer asked for in writing, whether the order is for…
A staff dashboard has to know what the person in front of it may see before it renders anything. The direct way is to ask about each protected area and see which answers come back. Every one of those questions is legitimate, and the browser…
Two failures in the same period, and neither was a defect in the product. A totals assertion failed once in a run and passed on the retry. A later step in an unrelated scenario answered not-found for a row the test had just created. Both…
Structural changes had accumulated on the mainline and had never been applied where the data lives. Applying them there is a one-way door, so the question worth answering first is not whether the history replays but whether it applies to a…
Bringing a business's catalogue onto the platform in one upload is a different problem from editing it. The failure that actually hurts is not a wrong cell; it is a partly written catalogue somebody has to reconcile by hand, late, on the…
Delivery priced by area is easy to describe and awkward to implement honestly, because three different situations look identical from inside a lookup that misses: the point is inside an area the business serves, the point is outside every…
Every support conversation about a platform starts the same way: something went wrong, on some screen, at some point today. Without a shared identifier, the account the customer gives and the account the server keeps cannot be joined, and…
method
Not a changelog entry and not a repository summary. One decision, one incident, one reversal, or one hard-won invariant — the thing an engineer would tell you at a whiteboard.
Prefer records with dates and root causes? Those are on incidents. Live numbers are on stats.