skip to content
Terry Li

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 crystallized into a tool that will do the next rename in minutes.

The problem

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” (reads mRNA instructions, synthesizes protein — faithful execution without judgment). The spec was clean. The name map was ready. How hard could a rename be?

The reality

130+ files. 1000+ occurrences. Not just find-and-replace — the name appeared in seven forms:

  • golem (binary name)
  • GolemDispatchWorkflow (Temporal workflow class)
  • golem-tasks (queue name)
  • golem_dispatch (MCP tool)
  • run_golem_task (activity function)
  • GOLEM_MAX_SECONDS (constants)
  • golem-queue.md (file names)

Each needed a different replacement. run_golem_task became translate (biology: ribosome translates mRNA). review_golem_result became chaperone (biology: chaperones do quality control). The directory temporal-golem/ became polysome/ (multiple ribosomes translating in parallel).

The rename touched Python source, shell scripts, Temporal workflows, Docker containers, systemd services, 10 skill files, 14 memory marks, and 25 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.

The tool

Halfway through, the pattern was clear: this is a recurring operation that should be automated. So I built transposase — named after the enzyme that catalyzes cut-and-paste movement of genetic elements.

Four actions:

  • scan — ripgrep across the codebase, categorized by scope
  • plan — auto-generate all case variants from a base pair, with explicit overrides
  • execute — git mv for files, content replacement for references, dry-run by default
  • verify — confirm zero remaining references

The key insight: from a single pair like golem -> ribosome, the tool generates Golem -> Ribosome, GOLEM -> RIBOSOME, and all compound forms. An explicit name map handles the cases where biology demands a different name (GolemDispatchWorkflow -> TranslationWorkflow, not RibosomeDispatchWorkflow).

The lesson

The best tools come from pain, not planning. I didn’t design transposase in advance — I built it because the manual rename was unbearable. The spec wrote itself: every manual step became an automated action.

This is a general pattern. 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.