6.4
The Smallest Safe Change
Why this exists
You've read the system, read its errors, and investigated without touching anything. Now you fix something — for the first time, on a system you didn't build.
The temptation at this exact moment is to fix everything you noticed on the way. Resist it. Not out of caution for its own sake, but because a small change that works teaches you more than a large one that mostly works.
The idea
Change one thing. Prove it worked. Stop.
The rule that makes changes safe on a system you don't fully understand:
If it breaks, you want to know exactly what caused it.
That's only true if one thing changed. Five changes shipped together means five suspects and no way to narrow it down without undoing all of them.
The loop, and you already know most of it:
| Step | From |
|---|---|
| Branch | 4.3 — risky work happens off to the side |
| Make the change — one | new |
| Read the diff | 5.3 — did it change only what you asked? |
| Prove it worked | 5.3 — evidence, not the summary |
| Commit and merge | 4.2, 4.3 |
| Check it live | 5.4 — local isn't live |
Everything here is a habit you already have. The only new part is that the thing you're changing belongs to someone else.
"Prove it worked" is the step to get right. Not "the error stopped". Not "Claude says it's fixed." Show the behaviour is correct now and was wrong before. Ideally you can point at the same evidence twice — the failing thing failing, and then the same thing passing.
Smallest means smallest. If the fix is one line, change one line. Don't tidy the file while you're in there, don't rename the confusing variable, don't fix the other thing you spotted. Those are separate changes and they can each be small too. Bundling them feels efficient and costs you the ability to say what broke.
One thing worth naming: you will be tempted to fix things you don't fully understand, because Claude will offer a plausible fix and it'll probably work. Sometimes that's fine. But if you can't say why the change fixes the problem, you haven't fixed the problem — you've changed something and the symptom went away, and those are different, and the difference shows up later.
Do
Use a real system. A defect from 5.3, a real small bug, or something genuinely broken.
- Pick one small thing to fix. If you can't describe it in a sentence, it's too big.
- Capture the problem first — a screenshot, the error, the wrong number. You need the "before."
- Make a branch.
- Fix it. One change. Write down anything else you're tempted to fix and leave it alone.
- Run
git diff. Read every line. Confirm nothing changed that you didn't ask for. - Prove it. Same evidence as step 2, now correct.
- Ask yourself in writing: why does this change fix the problem? If you can't answer, stop and understand it before merging.
- Commit, merge, ship, check live.
- Write
fix.md: what was wrong · what you changed · why that fixes it · the before and after evidence.
Step 7 is the one that separates fixing from poking. It takes thirty seconds and it's the difference between a fix and a coincidence.
Done when
Never do
Never bundle fixes. Five changes shipped together is five suspects when something breaks and no way to narrow it down without undoing all five.
Never ship a fix you can't explain. "The symptom went away" is not "the problem is fixed." One of those comes back.
Never fix straight onto the main branch. You have branches. They exist for exactly this — work you're not certain about on a system you don't own.