I renamed one concept across 130 files today. It took two hours, dozens of AI agents, and eight failed pushes. By the end, the pain had crystallised into a tool that will do the next rename in minutes.
My AI coding system uses cell biology as its naming convention. Every component has a biological identity — ribosome, translocon, sortase. But one holdout remained: “golem,” the task executor. No biology. Just a fantasy name surrounded by biological names. The fix was obvious: rename it to ribosome, which reads mRNA instructions and synthesises protein — faithful execution without judgment. The spec was clean. The name map was ready. How hard could a rename be?
A hundred and thirty files. Over a thousand occurrences. Not just find-and-replace — the name appeared in seven forms: the binary name, a Temporal workflow class, a queue name, an MCP tool, an activity function, constants, and file names. Each needed a different replacement. The activity function became translate, because in biology the ribosome translates mRNA. The review function became chaperone, because chaperones do quality control. The directory for parallel workers became polysome, because multiple ribosomes translating simultaneously is a polysome. The rename touched Python source, shell scripts, Temporal workflows, Docker containers, systemd services, ten skill files, fourteen memory marks, and twenty-five test files. Pre-commit hooks caught pre-existing lint in every touched file. The push was blocked by integration tests that connected to a live server still running the old code.
Halfway through, the pattern was clear: this is a recurring operation that should be automated. So I built transposase — named after the enzyme that catalyses cut-and-paste movement of genetic elements. Four actions: scan the codebase with ripgrep and categorise by scope, plan by auto-generating all case variants from a base pair with explicit overrides, execute with git mv for files and content replacement for references in dry-run by default, and verify that zero references remain. The key insight: from a single pair like golem to ribosome, the tool generates the title case, upper case, and all compound forms automatically. An explicit name map handles the cases where biology demands a different name — the workflow class becomes TranslationWorkflow, not RibosomeDispatchWorkflow.
The best tools come from pain, not planning. I did not design transposase in advance. I built it because the manual rename was unbearable. The spec wrote itself: every manual step became an automated action. The second time you do something manually, you should be suspicious. The third time, you should be building a tool. But sometimes the first time is painful enough that the tool is obvious before you finish.