The Smallest Safe Change: A Branch-Level Refactor Workflow for Messy Repos

Refactoring code is often fraught with peril. While the test suite remains green, a wide-ranging change can still cause a bug to ship. To minimize risk, it is best to make small, incremental changes, touching only one branch of code at a time. Characterization tests lock that branch down before any further modifications are made. This approach works even on messy, legacy codebases.

The size of the branch matters. A single line in a diff can alter multiple branches, while a large number of lines may affect none at all. The safe unit for a refactor is a branch, not a line of code. Count every direct if condition in the function. Each refactor should change no more than one branch.

Consider a messy Python module with a function that carries a hidden global side effect. This function is a perfect target for this refactor technique. The first step is to pick a sealed unit - a function that returns a plain value and may mutate a known global list, but does not read time, randomness, or the environment.

In the original code, there are three independent conditional branches. One branch depends on the mutated base value, and the side effect list must be locked as well. Next, build a boundary grid. The branch base 500 demands a boundary test, including both 500 and 501 in the price grid. Use local, remote, and other as zones, and two weight classes for better coverage.

The Cartesian product gives you a complete grid. Record the current behavior by running the legacy apply_surcharges function with each combination of prices, zones, and weights. The results, including both the base value, zone, weight, result, and messages, are saved to a characterization.json file. This JSON file serves as the refactoring contract, an honest snapshot of the current bugs.

Before attempting any refactoring, lock the state with a test. Read the recorded JSON snapshot file, re-run the original function, and compare the return value and side effect list. Use pytest to parameterize the cases from the characterization.json file. The test passes cleanly, establishing a reliable behavioral oracle.

Finally, use a model to ask for a complete branch inventory list. MonkeyCode's free model can provide a surprisingly useful breakdown of the function. Verify every line of the model output against the source code to ensure accuracy. The model output can then be treated as a testable hypothesis. By following this step-by-step workflow, you can safely refactor even the most messy, legacy codebases, one branch at a time.