Cap the Diff at One Seam: Picking the Smallest Safe Refactor After Characterization

Characterization tests tell you what the code does. They do not tell you where to stop. The smallest safe change is a budget decision, not a testing decision.

This post covers the second half of a messy-repo refactor. Assume the golden corpus already exists. The job now is to bound the edit before the first keystroke.

All code below is illustrative. Nothing here was executed against a real repository. Treat every number as a placeholder you replace with your own measurements.

1. Write the seam ledger before you open the editor

A seam is one place the outside world touches the messy code. List them first. Do not list functions you find interesting.

Write it as data, not prose. A YAML file version-controls well and diffs cleanly in review.

# seam_ledger.yaml — illustrative template, values are placeholders seams: - id: pricing.rounding entry: billing/pricing.py::apply_discount callers: 7 side_effects: none pinned_by: tests/characterization/test_pricing_golden.py allowed_diff: "<= 15 lines, one function" rollback: "revert one commit" - id: import.invoice entry: billing/invoice.py::load_partner_feed callers: 2 side_effects: [network, filesystem] pinned_by: none allowed_diff: "do not touch" rollback: n/a

Two rules make the ledger useful. First, a seam with pinned_by: none gets no edit permit. Second, a seam with side effects needs a wider budget or none at all.

Count callers mechanically, not by memory. Grep the import sites and record the number.

grep -rn "apply_discount(" --include='*.py' src/ | wc -l

Record the output. That count becomes your guard later.

2. Pick one seam, and pick a cheap one

The first refactor should optimize for rollback speed, not for payoff. Choose the seam with few callers, no side effects, and an existing pin.

Use this decision table. Read the row that matches your seam.

Callers	Side effects	Pinned by corpus	Allowed change
≤ 3	none	yes	extract one function, rename internals
≤ 3	none	no	add pins first, then stop
4–10	none	yes	one function body, no signature change
4–10	any	yes	inline only, no extraction
any	network or disk	any	observation only, no edit

The table is deliberately conservative. Its purpose is to make refusal cheap and defensible in review.

3. Set a numeric change budget

Vague scope becomes large diffs. Convert "smallest safe change" into two numbers: changed lines and changed files.

A gate script enforces both. Run it locally before pushing.

#!/usr/bin/env bash # gate.sh — illustrative; adjust paths and budgets to your repo set -euo pipefail BASE=${BASE:-origin/main} BUDGET=${BUDGET:-40} FILE_BUDGET=${FILE_BUDGET:-3} git diff --stat "$BASE"...HEAD CHANGED=$(git diff --numstat "$BASE"...HEAD | awk '{s+=$1+$2} END {print s+0}') echo "changed lines: $CHANGED" test "$CHANGED" -le "$BUDGET" || { echo "over line budget"; exit 2; } FILES=$(git diff --name-only "$BASE"...HEAD | wc -l) test "$FILES" -le "$FILE_BUDGET" || { echo "over file budget"; exit 3; } python -m pytest -q tests/characterization

The script fails loudly for three different reasons. That separation matters in CI logs. You want to know whether you broke behavior or merely broke scope.

4. Guard the seam count, not just the output

Output pins catch behavior changes. They miss structural drift. A refactor can keep every golden output identical while quietly doubling the call sites.

Add one cheap structural assertion. It counts text occurrences of the seam symbol.

# tests/test_seam_count.py — illustrative; substring counting is noisy by design from pathlib import Path def count_call_sites(symbol: str, root: str = "src") -> int: return sum( p.read_text(encoding="utf-8").count(symbol) for p in Path(root).rglob("*.py") ) def test_discount_call_sites_do_not_grow(): # Replace 7 with the number you measured in step 1.  assert count_call_sites("apply_discount(") <= 7

This is a smoke alarm, not a proof. Comments and strings will inflate the count. That noise is acceptable while the number stays flat.

Run the guard before and after the edit. Two runs give you a delta. One run gives you nothing.

5. Make the edit, then do a rollback drill

Apply one change from the decision table. Nothing else. No formatting sweep, no import sorting, no drive-by rename.

Then rehearse the rollback. Revert the single commit on a scratch branch and confirm the corpus passes again.

git revert --no-edit HEAD python -m pytest -q tests/characterization git revert --no-edit HEAD # restore the change

If the revert is not clean, your change was not small. Split it and restart at step 2.

Where a free model and a free host fit

Step 1 is the slow part. Reading call sites and filling the ledger takes attention, not cleverness.

MonkeyCode's free model access and free server option are relevant here, as operator-supplied availability. A free server can host the gate script for pull requests, so the budget check runs off your laptop. Free model access can draft candidate corpus inputs for human review.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Treat model output as a draft queue, never as approval. A human reads every proposed input and decides whether it pins real behavior. A model that guesses wrong adds a false pin, which is worse than no pin.