Hold the Wide Diff Until One Score Extract Passes

A wide model diff does not represent a complete refactor. Before accepting any split, ensure observable behavior remains unchanged. Refrain from extracting modules that intertwine input handling, scoring computation, and logging. Such messy modules contain three jobs within a single file. Reviewer feedback highlights that messy modules obscure how a single careless edit can affect all three jobs simultaneously.

This guide uses a small Python scoring module to demonstrate the process. All code snippets are for local use only and must be adapted with appropriate names and paths. The first step is to freeze the fixture set by selecting three inputs that already exist in the repository. These inputs should cover a happy path, an edge case, and a bad path.

Store these under a fixtures directory with stable names, avoiding any production data or customer files. The second step is to write a characterization test that captures the public function's behavior and compares it against a golden file. This test must pass after the smallest possible extract, ensuring observable behavior remains fixed.

The golden file should be version-controlled alongside the test. The third step involves re-running the test on unchanged code to verify that the golden file matches the current module. If the test fails, address the fixture bug before modifying production code. A flaky test result indicates a fixture issue, not a product problem.

The fourth step is to reject the wide model diff if it alters more than one concern. Focus on extracting a pure score function only, without touching file reads or log writes. Partial applies are discouraged as they hide the actual broken hunk. Once the smallest safe change is applied, re-run the characterization test to confirm that observable behavior remains intact.

If the log text changes, the extract was not pure, and the function should be reverted and the prompt adjusted accordingly. Only after a successful green result should a second extract be considered, targeting logging or file reads separately. Approval of subsequent extracts should be handled by the module owner, not the model.