Why AI Agents Rename the Wrong Things

A minified application may contain a local variable called a, an object key called a, a route segment called a, and an event payload field called a.

They look identical in text.

They are not the same kind of thing.

The local variable may be safe to rename. The object key may be serialized and consumed elsewhere. The route may be part of a public URL. The event field may be a wire contract shared with a server or another process.

A global cleanup instruction such as “replace unclear names with semantic names” collapses those differences. That is how a well-intentioned AI agent can make code easier to read while making the software harder to run.

The original name is not the goal

When minification removes an authored name, there may be no single original answer to recover.

A developer could have chosen:

• speed;
• velocity;
• carSpeed;
• movementRate;
• v.

The useful target is not the exact word the original developer happened to type. It is a name that communicates the observed role well enough for the next engineer to work safely.

That works in favor of semantic recovery. We do not need to read a former developer’s mind.

But it does not make renaming trivial.

The system still needs to answer two different questions:

1. What does this binding appear to mean?
2. Is this surface actually allowed to change?

The first can require judgment. The second should be governed by evidence and policy.

Meaning is distributed

A mangled identifier rarely explains itself at the declaration.

Its role may become visible through:

• constructor and runtime type;
• values sampled while the application runs;
• functions that read or modify it;
• UI labels or selectors associated with it;
• asset names;
• network paths;
• scene-graph relationships;
• animation behavior;
• object keys;
• import and export position;
• framework conventions;
• call-site arguments;
• error messages;
• tests or captured scenarios.

Suppose a value:

• is a Three.js mesh;
• receives keyboard-driven position updates;
• is followed by the camera;
• collides with the ground;
• owns an animation mixer;
• is created near the player spawn point.

mesh is technically true but weak. playerMesh is stronger. vehicleBody may be stronger still if the evidence shows a car rather than a character.

The model can help interpret that combined evidence.

It should not have to rediscover all of it from an anonymous bundle.

The protected-surface problem

Some names are not merely names. They are contracts.

Common examples include:

• routes;
• storage keys;
• cookie names;
• event names;
• network methods and paths;
• JSON and message payload keys;
• feature-flag names;
• shader uniforms and source strings;
• GLTF node names;
• asset URLs and filenames;
• worker entry paths;
• package exports;
• browser-extension message types;
• CLI flags;
• configuration keys;
• CSS selectors used by automation or integrations.

A change may pass formatting, parsing, type checking, and build while violating one of these surfaces.

The failure may appear only:

• after a reload;
• in another browser tab;
• after a specific interaction;
• when old saved data is read;
• when a server responds;
• when a 3D asset is traversed;
• when another package imports the old symbol;
• when a service worker restarts.

This is why “the build passed” is weak evidence for a rename campaign.

Binding identity matters more than text

A safer rename system does not start with character replacement.

It starts with binding identity.

The system should know:

• which declaration is being renamed;
• which references resolve to that declaration;
• whether a same-named binding exists in another scope;
• whether object-property shorthand changes meaning;
• whether string or property surfaces are intentionally excluded;
• whether exports or imports must remain stable;
• whether the destination collides;
• whether generated and authored regions are mixed;
• whether the evidence still matches the current source hash.

Once the decision is accepted, the mutation should be mechanical and repeatable.

The model can say:

This binding represents the active camera target. Rename it to cameraTarget.

The mutation engine should then determine the exact edit set, preview it, reject collisions, avoid protected surfaces, apply it transactionally, and run the required checks.

The model supplies meaning.

The system retains edit authority.

Confidence should affect the lane

Not every rename deserves the same treatment.

A practical system can separate candidates into lanes.

High-confidence, low-risk

Example:

• the binding is a local DOM element;
• its text is “Submit”;
• it is used only in the click handler and validation flow;
• no protected or public surface is involved.

A deterministic actuator may be able to apply a reviewed semantic name automatically and verify the result.

Medium-confidence

Example:

• runtime evidence suggests a scene object is a camera target;
• two names are plausible;
• the binding crosses several modules;
• the rename has a clear reversible plan.

This is a good bounded judgment task.

Low-confidence or protected

Example:

• the same text appears in serialized payloads;
• runtime evidence is sparse;
• source maps conflict;
• the object is shared across an initialization-sensitive closure;
• a public export or route may change.

The useful output is a refusal, an unresolved label, or a request for more evidence—not a polished guess.

Why stronger models still make mistakes

A stronger model may be better at reading a large evidence packet, understanding an application’s domain, and choosing consistent names across modules.

It still cannot know facts that were never collected.

It cannot infer a hidden storage consumer from intelligence alone. It cannot prove a route is unused without observing or analyzing the relevant surface. It cannot know that a shader uniform is addressed dynamically if the workflow never exposes that behavior.

This is an information problem before it is a model problem.

Better models improve judgment.

Evidence and guards determine whether that judgment is safe to act on.

Renaming should create a durable record

A trustworthy rename is more than a changed identifier.

Its record should preserve:

• source checkpoint;
• binding identity;
• evidence references;
• selected name;
• rejected alternatives where useful;
• decision source;
• confidence;
• mutation plan;
• preview hash;
• applied patch;
• checks run;
• resulting checkpoint;
• later correction or survival.

That history matters for more than audit.

Repeated accepted decisions can reveal patterns that later become deterministic rules. Repeated reversals reveal weak evidence classes. Rename chains can show that an early generic label was eventually refined.

The system learns from outcomes without pretending every first choice was final.

What Kalu Kode is building toward

In KodeBack, semantic names help turn recovered code into an understandable workspace.

In KodeProof, the same principle applies to risky refactors: an agent should not be allowed to spread a semantic choice through the repository without a declared and reviewable transaction.

The common workflow is:

1. Collect and bind the relevant evidence.
2. Identify surfaces that must not change.
3. Ask for one bounded semantic decision where needed.
4. Convert the decision into an exact mutation plan.
5. Apply through a controlled actuator.
6. Check behavior, contracts, and source structure.
7. checkpoint or roll back.
8. Record what happened.

The goal is not to remove AI from semantic cleanup.

It is to stop using AI judgment as a substitute for source identity, contract inventory, and controlled mutation.

A good rename makes code clearer.

A trustworthy rename also explains why that clarity did not come at the expense of the software’s behavior.