A refactoring folder that reviews my codebase for me

Buildom is six weeks into active development and it already had two full refactoring waves. The first one fixed 23 documented problems across five phases, the second consolidated config, HUD context and block id types. Both times the same fear showed up afterwards: did the new growth quietly undo what we fixed?

My answer to that is a folder: docs/refactoring/. It has two subfolders and one rule that changed how I think about code health.

done: write it down, then never touch it again

The done/ folder holds the original architecture analysis, five phase documents, each with problems, solution sketches and acceptance criteria. After execution they became historical documents. The README says it explicitly: do not re-implement anything from here, and where a phase document contradicts the code, the code is right.

The acceptance criteria turned out to be the hidden gem. Phase 3 demanded a GameCanvas under 100 lines and a frame function that just delegates. Those numbers do not expire. Six weeks later they are the exact rulers I measure new growth against.

open: everything gated until proven

The open/ folder is where ideas wait, each in its own file with problem, sketch and acceptance criteria. The key design decision: the three performance items are gated on profiling. Minimap partial updates only happen when a rebuild measures over 2 ms. The torch cache dirty flag waits for a scan over 2 to 3 ms. No speculation, no premature optimization, just a condition and a plan.

That discipline is harder than it sounds. When I re-reviewed the folder this week, my instinct was to implement the minimap optimization because it is clever. The code said otherwise: there is a canvas cache in front of it, the rebuild only runs on revision bumps, and nobody has measured it as slow. So it stays open.

The part I added this week: regression indicators

This week I re-assessed the whole folder against the current codebase and rebuilt the README around one idea: the next review should not require re-reading anything. So the README now has three new sections.

First, a re-assessment procedure. Measure file sizes, list the hotspots from the git log since the last review, check the indicators, verify the open items against the code, write the result back. Six steps, with the shell commands included.

Second, a health snapshot with a verdict and a date. This week’s verdict: no large refactoring needed, all 23 fixes intact, but two files are carrying the structural cost of the last two weeks.

Third, and this is my favorite part, a regression indicator table. Indicator, limit, measured value, source. GameCanvas: limit 100 lines, currently 720, flagged. engine.ts: limit 500, currently 948, flagged. Raw console calls in game code: limit 0, currently 0, passing. The persistence hook defaults: were still true, are now false, passing.

READMEs written for the AI

Here is the trick behind that folder: the README is not documentation for me, it is an instruction manual for the AI. It opens with a section called “How to re-assess the project (read this first)”, a six step procedure with the shell commands spelled out. Measure file sizes, list the hotspots from the git log, check the indicator table, verify the open items against the code, write the result back, end with a verdict. Step five even says to update the date and the measured column in the README itself, so the document stays alive.

That changes the workflow completely. When the game has grown for a few weeks, I do not sit down and remember how we reviewed things last time. I open the folder and say: follow the README. The agent measures, compares, reports, and writes the new numbers back. The verdict I get back this week was a direct product of that: no refactoring needed, two files flagged, one item closed, next steps ordered by priority.

I use the same pattern everywhere now. The ai-log folder has a README defining the entry format, the refactoring folder has this one. Every folder I create gets a README whose first job is to instruct the next agent session, not to describe the folder to a human visitor. A README that only describes is a museum plaque. A README that instructs is a teammate.

The limits are not invented, they come from the acceptance criteria in done/. That closes the loop: a phase defines a target, the table guards it forever, and every future review is a two minute measurement instead of a three hour audit.

What the numbers actually caught

The review found something I would have sworn was fine: nothing regressed. All the shared physics, the event bus, the O(1) atlas lookups, the logger, still in place after 28 commits. But the two monolith problems phase 3 solved had grown back to 720 and 948 lines, and the persist hooks still had the unsafe default that one URL race already exploited once. Concrete, measurable, and now written down with a recommended order attached.

In four weeks the game will have grown again. Instead of dreading the question “does this need a refactoring”, I will read one README, run two commands, update one table, and get the answer. If you keep a game or any long-lived codebase alive with heavy AI assistance, steal this structure: done stays historical, open stays gated, and the indicators keep the score.