Pin the Fault Matrix Before You Refactor a Messy Module

The article emphasizes the importance of addressing the error surface before refactoring a module. In a composite scenario, a service module grows to 900 lines, a refactor diff reaches 400 lines, and the test suite initially passes. However, later integration fails due to a change in validation handling. The article argues that the first thing to change in a refactor is usually not the happy path, but the error surface, which includes exception types, error codes, and validation order. The key points are:

1. The error surface changes first in a refactor, unlike the happy path.

2. Happy paths are easy to observe and assert, while error paths require deliberate fault injection and are less pleasant to demonstrate.

3. Three patterns cause drift in the error surface:

- Type flattening: specific errors collapse into ValueError or Exception

- Code loss: the class stops carrying the code attribute

- Ordering drift: validation runs in a new sequence

4. To address this, enumerate every raise site as data using Python's standard library, specifically `ast.unparse` for versions 3.9 or newer.

5. Create a fault matrix with one row per fault class, asserting on the code column and treating prose as a secondary signal.

6. Record which layer raises the exception, as this helps detect when a layer is moved during refactoring.

7. Keep the matrix in version control alongside tests to make behavior changes reviewable.

The author stresses that the diff from a baseline raise site count to the post-refactor count tells you exactly which raises moved, appeared, or disappeared during the change. This process ensures a systematic approach to refactoring while maintaining error handling stability.