The "explain before you touch it" refactor prompt

Before changing anything, read this code and tell me back, in plain English:
1. What it does, step by step.
2. The inputs, outputs, and any side effects.
3. The two or three things most likely to break if I change it.

Then STOP and wait for me to confirm your understanding is correct.

Only after I say "go" should you propose a refactor — and when you do, make
the smallest change that achieves the goal, preserve existing behaviour, and
explain what you changed and why.

Most bad AI refactors fail for the same reason bad human ones do: the change happened before the understanding did. This prompt inserts a checkpoint.

Why it works

• It separates comprehension from action. You get to catch a wrong mental model before it’s been baked into a 200-line rewrite.
• The “STOP and wait” line matters. Without it, models barrel ahead. With it, you get a cheap, reversible review step.
• “Smallest change that achieves the goal” is the phrase that prevents the model from rewriting your whole file because it felt like it.

How to use it

Paste it, then drop in the code (or point your agent at the file). Read the model’s summary like you’d read a junior dev’s — if step 1 is wrong, the refactor would have been wrong too. Correct it, then say “go”.

Variations

• Swap “refactor” for “add a test for” and it becomes a great test-writing prompt.
• For reviews, end with: “…then list issues by severity, not by line order.”
• Working with a smaller local model? Keep the code under ~300 lines so the understanding step stays accurate.

This one earns its keep every single day.