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.
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…
A written contract and a shipped implementation drift apart in one direction: the implementation wins and the document becomes archaeology. Two practices in this period worked against that.
A development database was published on every network interface rather than the loopback one. It was found by a scanner, brute-forced, and left carrying a back door. Nobody had decided to expose it. The default mapping did that, and every…
A live board for staff is a latency problem that is really a truth problem. The obvious implementation is an in-process broadcast: when state changes, publish. It is fast, it is simple, and it makes it possible for a board to display a…
Verification kept producing a specific kind of wrong answer. The tree was correct, the local build was correct, the browser checks were green, and the thing users were actually loading was older than all of it. Two mechanisms were…
Sample content has a way of surviving into production. A review section carried a demonstration fallback: a few plausible reviews and an average just under five stars, rendered when the real fetch failed. It existed to make review builds…
Per-customer difference is where products fork. One business wants the offers in the sidebar, another wants them as a strip; one wants a denser grid. The fast answer is a branch, then a build flag, then a separate deployment, and then…
Bringing a new business onto the platform looks like one operation and is really two. There is the record of the business: its identity, its routing key, its configuration, and a starter menu attributed to it. And there is the deployment of…
Every name the platform answers on should get a real certificate. Names that resolve to the origin but match no route fall through to a default, self-signed one — a small leak, a real annoyance, and the kind of thing that gets fixed by…
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.