Predicting your own failure modes

A field note from Chad Mathews, drafted with Claude. Chad directs the work and lived these decisions; Claude does the writing; Chad edits every line and approves it before it publishes. Where an idea or a reference came from Claude, the note says so.

Most of my bugs are not surprises. After enough time on a project, the same categories of thing break in the same predictable ways, and I can usually name them before they happen. The waste is not the bug itself. It is hitting a bug I could have called, spending an afternoon diagnosing it from scratch, and only then remembering that I knew this was coming. So I keep a file whose only job is to write down how the project will probably break next.

The bug I had already predicted

Here is the one that made me start taking this seriously. In my game, the rooms do not sit at the origin. They are laid out across the world at a large offset, thousands of pixels over. Any code that moves an object around inside a room has to be careful about which coordinate space it uses: the room’s own local space, or the global world space.

Get that wrong and you get a very specific bug. A piece of machinery whose movement is clamped to the room’s bounds, but written against the global position instead of the local one, will teleport itself clean out of the room the instant it runs. And it will pass every test I throw at it, because my tests run at the origin, where local and global happen to be the same number. The bug is invisible until the thing is sitting at its real offset in the real level.

I knew this. It had bitten me once already, so I wrote it into the risk file in plain language: mechanism math goes in local coordinates, and test it at a non-zero offset, because an origin-only test will lie to you. The next time I built a moving mechanism, that line was sitting there in the preflight. I tested it at the offset first. The bug that would have eaten an afternoon showed up in five minutes, exactly where the note said it would.

Why this is its own file

I keep a separate file of things I have decided not to build, so the AI stops re-proposing them. This is not that. That file is a list of settled noes. This one is a list of predicted failures: not “we rejected this,” but “this will probably go wrong, in this way, and here is the check that catches it.” One guards decisions. The other guards execution.

The entries are not vague worries. Each one names a system, the specific way it tends to break, and the smallest check that would catch it. “Enemies placed in a room can wake up before the player exists, so if one animates but never chases, check whether it found the player group before you go retuning its ranges.” That is a prediction with a diagnosis attached. When the symptom appears, I am not debugging from zero. I am confirming a guess.

The old name for this

I did not reach for a name when I started this. I just got tired of solving the same predictable problem twice and started writing the predictions down.

The names came up while Claude and I were writing this note. The front half of what I do is a pre-mortem: before the work, you imagine it has already failed and write down every reason why. The file itself is close to what reliability engineers call a risk register or a failure-mode analysis, cataloguing how a system can break and what each failure would cost. I had not used any of those terms. Recognizing my risk file inside them was the reassuring part: a decent sign that the habit was sound and not just my own private superstition.

The honest limit

A prediction file is not a crystal ball, and the real trap is treating it like one. You cannot foresee every failure, and if you try, you drown the useful predictions in a swamp of paranoid ones nobody reads. The file is only worth keeping if it stays honest: entries earn their place by having actually happened at least once, or by being specific enough to convert into a real check. Vague dread does not qualify.

So it is a living document, not a plan. It gets refined from real evidence, tightened when a prediction comes true, and pruned when a system stabilizes and the risk stops being real. The point is not to know the future. It is to stop paying full price twice for the failures I can already see coming.