The Shape of a Safe Upgrade: Write It Down Before You Build It

Two jobs, one lesson

Last week I wrote about the bugs that taught me to check a claim before I accept it. This week is the other half of that habit: the work that went well, and why. Both stories come down to the same thing. Before you build, write down what done looks like, in a place where someone who is not you can check it.

The upgrade, and the shape of a safe one

We moved the whole project up an engine version in one night. I want to describe how, because the method is the transferable part, and it is not clever. It is boring on purpose.

It ran on a copy of the project, never the real one. It ran as a written list of gates: build, tooling, plugins, save format, every shipping map, a full asset resave, a cook, and a real play session, each with a written pass or fail recorded before moving on. The real project only moved after every gate passed. The worst case for the entire operation was deleting a folder.

It surfaced one subtlety worth knowing: some vendor assets carry stale internal identifiers across engine versions. Fixing those meant byte level backups first and a byte level comparison after, so we could prove we changed exactly what we meant to change and nothing else.

Two more things I would tell anyone about to do the same:

• Put the gate list in a file before the first step runs, and record each result as it happens. A gate you grade from memory the next morning is a gate you will grade generously.
• Let the copy absorb every surprise. Ours took a broken vendor sound asset, a wrong folder rename, and a full asset resave before the real project ever changed. None of that touched anything I would have had to undo.

What changed: nothing, and that is the point. This one went well because we treated it as a checklist rather than a leap. The bugs from last week are what happens without gates. This is what happens with them.

The result I did not believe, and the reset that followed

I asked for three generated biomes. What came back was one that genuinely worked and two that missed badly enough that I said so in plain words.

My instinct was to ask again, more clearly. That instinct was wrong. The problem was not the request. The problem was that "a good biome" existed only in my head, so nobody could check against it.

So we stopped and wrote it down: how long a layer should take to cross, how many layers chain together, that pathing has to read from an isometric camera, that enemies are placed by rules rather than by hand, that a run ends somewhere that feels like a destination. That definition now lives in a file every future work session has to read, and every generation decision since has been tested against it.

The forest that came out of it is the first level I would put on camera.

What changed: when you get a result you do not believe, the fastest way out is almost never a better prompt or a longer conversation. It is a definition of done that lives outside your head, where it can be checked by someone who is not you. This is equally true of AI teammates and human contractors, and I learned the contractor version the expensive way last year.

Why these two belong together

A gate list and a definition of done are the same tool pointed at different moments. One says what must be true before we move. The other says what must be true before we call something finished. Both take an hour to write and both pay that hour back the first time they catch something. The month I skipped them cost me nights. The night I used them cost me a folder.

The goals board shows what is in flight now that the engine move is behind us. Statuses, not dates, because I would rather show you what is true than what I hope will be true.

If you are planning an engine move of your own, or trying to get a generator to produce something you would actually ship, I am happy to compare notes: info@viseterna.com reaches me.