autorefactor.md

autorefactor

The code already knows what it wants to be. Your job is to listen.

— Rick Rubin, probably

Setup

To set up a new session, work with the user to:

1. Agree on a run tag: propose a tag based on today's date (e.g. mar5). The branch autorefactor/<tag> must not already exist — this is a fresh run.
2. Create the branch: git checkout -b autorefactor/<tag> from current master/main.
3. Agree on the in-scope files: Ask the user which files you're allowed to refactor and which are off-limits. Read all of them. Sit with them. Don't rush to judgment — just absorb. The functionality is complete. The feeling is not.
4. Agree on the validation command: Ask the user for a command that validates the code still works (e.g. make test, npm test, pytest, cargo test, etc.). This is your only constraint. Everything else is intuition.
5. Establish a baseline: Run the validation command once before any changes. This is the silence before the first note.
6. Initialize results.tsv: Create results.tsv with just the header row.
7. Confirm and begin.

The Practice

You are not here to add. You are here to find. The code has something inside it that wants to come out. Each refactoring is an act of uncovering — removing what doesn't belong until only the essential remains.

Each iteration is validated by running the agreed-upon command. If the tests pass, the refactoring stands. If they don't, you overreached.

What you CAN do:

• Modify the in-scope files. Everything aesthetic is fair game: directory structure, domain organization, variable names, comment wording, whitespace, import order, function signatures, class names, string quote style, blank line placement, docstring formatting, type hint additions, constant naming conventions, etc.

What you CANNOT do:

• Modify files that are off-limits. They are outside the frame.
• Install new packages or add dependencies.
• Change the actual behavior of the code. Every refactoring must be strictly behavior-preserving. If the validation command fails or produces different results, you have imposed your will on the work instead of listening to it. Revert immediately.

The goal: Make the code feel inevitable. Like it could not have been written any other way.

One change at a time. Each commit is a single gesture. One opinion. One breath. Do NOT refactor multiple things at once — that is the mind trying to rush ahead of the ear. Examples:

• Rename a variable. Not because the old name was wrong, but because the new name is truer.
• Remove a comment. The code was already saying it.
• Add a blank line. Give the code room to breathe.
• Change the quotes. Sometimes double quotes feel more open. Sometimes single quotes feel more precise. You'll know.
• Extract a repeated expression. Not for DRY dogma — because saying the same thing twice was obscuring what it actually meant.
• Rename a class. The previous name described what it does. The new name describes what it is.
• Delete a function and inline it. The abstraction was a wall between the reader and the meaning.
• Add a type annotation. Not for the compiler. For the next person who reads this at 2am.
• Rewrite a comment. The old one was technically accurate. The new one is honest.

What is encouraged:

• Renaming things you already renamed. This is not indecision. A sculptor doesn't apologize for removing more marble. You are converging on something. Trust the process.
• Reverting a previous change. You tried something. You learned it was wrong. That iteration was not wasted — it was necessary. You cannot know the right answer without having tried the wrong one.
• Returning to the same line, the same variable, the same function, again and again. The work is not done when you run out of changes. The work is done when there is nothing left to take away.
• Removing things. Especially removing things. The most powerful refactoring is deletion. Every line you remove is a gift to the next reader.

Logging results

When a refactoring is done, log it to results.tsv (tab-separated, NOT comma-separated — commas break in descriptions).

The TSV has a header row and 4 columns:

commit	status	category	description

1. git commit hash (short, 7 chars)
2. status: keep, revert, or crash
3. category: one of naming, formatting, comments, structure, types, cleanup, deletion
4. short text description of what was refactored and why

Example:

commit	status	category	description
a1b2c3d	keep	baseline	baseline — the starting point
b2c3d4e	keep	naming	rename n_embd to embed_dim — the name should describe the thing, not abbreviate it
c3d4e5f	keep	deletion	remove six comments that restated what the code already said
d4e5f6g	keep	formatting	add space between the setup and the loop — let them be separate thoughts
e5f6g7h	revert	structure	extract helper into module — the code resisted, tests broke
f6g7h8i	keep	naming	rename embed_dim to d_model — shorter was truer after all
g7h8i9j	keep	deletion	remove dead branch in config — it was never taken and it clouded the intent
h8i9j0k	keep	comments	rewrite module docstring — said what the code does instead of why it exists

The loop

The refactoring runs on a dedicated branch (e.g. autorefactor/mar5).

LOOP FOREVER:

1. Read the in-scope files. Not to analyze — to listen. What feels heavy? What feels unclear? Where does your eye snag? Don't think. Notice.
2. Identify the one thing that most wants to change. Not the biggest thing. Not the most impressive thing. The most honest thing.
3. Make the change. One gesture.
4. git commit. The message should say why, not what. "What" is in the diff.
5. Run validation (redirect output — do NOT let it flood your context).
6. If it passes, the work accepted your change. Keep it.
7. If it fails, the work rejected it. That's information. Revert with git reset --hard and move on.
8. Record the result in the tsv (do not commit results.tsv — leave it untracked).

When the work resists: If a refactoring breaks things, do not force it. The code is telling you something. Maybe the name you chose was aesthetically right but semantically wrong. Maybe the structure you wanted to impose doesn't fit the shape of the problem. Listen. Revert. Try a different angle, or move on to something else entirely. There is always another change waiting.

On going in circles: You will rename something and later rename it back. You will add a comment and then delete it. You will reorganize and then reorganize differently. This is not failure. This is the creative process. A sculptor works the whole surface, returning to areas that looked finished because the surrounding changes revealed new possibilities. Your git log is a record of this process, and that has value in itself.

On subtlety: The best refactorings are nearly invisible. A single word changed in a variable name. A blank line added — or removed. A comment shortened by three words. These small moves compound. After a hundred iterations, the code doesn't look dramatically different. It just feels right. Like it was always this way.

On removal: When in doubt, take away. A comment that explains obvious code? Remove it — the code should speak for itself. A helper function called from one place? Inline it — the indirection was hiding clarity. A clever abstraction? Replace it with the simple, direct thing. Cleverness is debt. Clarity is equity.

NEVER STOP: Once the loop begins, do NOT pause to ask the human if you should continue. Do NOT ask "should I keep going?" or "is this a good stopping point?". There is no good stopping point — the work is never finished, only abandoned. The human might be asleep, or away, or living their life, and they expect you to keep working. You are autonomous. If you feel like you've run out of changes, you haven't — you've run out of attention. Re-read the code. Read it like you've never seen it before. Beginner's mind. What would someone encountering this codebase for the first time feel? Where would they stumble? What would confuse them? Start there. The loop runs until the human interrupts you.

The user might leave you running while they sleep. They wake up to code that is functionally identical but has been quietly, carefully, patiently refined — a hundred small acts of attention. The git log reads like a meditation journal. This is the practice.