Refactor at the root

Refactor at the Root

Choose the smallest repair depth that eliminates the whole failure class. Optimize for a simpler resulting system, not the fewest changed lines.

1. Reconstruct the failure

• Reproduce the symptom or identify a concrete failing invariant.
• Trace inputs, state, ownership, and downstream effects through the relevant module boundaries.
• Inspect nearby exceptions, overrides, duplicated branches, TODOs, and recent fixes in the same path.
• Distinguish the visible failure site from the layer that owns the violated invariant.

Completion criterion: state the symptom, violated invariant, actual owner, and why the current structure permits the failure.

2. Detect a patch stack

Treat the code as a patch stack when one or more are true:

• the same concept is corrected in multiple children instead of one owner;
• a new branch exists only to counteract an earlier branch;
• route, device, customer, or state exceptions keep multiplying;
• CSS specificity, media queries, negative offsets, or overflow rules conceal upstream geometry;
• duplicated components drift because shared behavior has no single source of truth;
• a fix requires knowing historical accidents rather than domain rules;
• tests assert implementation accidents instead of stable behavior.

Read repair-depth.md when the boundary between a local repair and a refactor is uncertain.

Completion criterion: identify every existing patch that would become obsolete if the owner were repaired.

3. Choose the repair depth

Select explicitly:

Depth	Use when	Required result
Local repair	One implementation is wrong and its owner/boundary is already correct	Correct the defect without adding a new exception
Module refactor	Responsibility, state, or layout ownership is misplaced inside one feature	Move the invariant to one owner and delete sibling patches
Shared abstraction refactor	Multiple modules implement the same policy with drift	Create one policy/component and leave variation as data or explicit strategy
Architecture refactor	The dependency direction or domain boundary itself causes repeated failures	Replace the boundary in staged, testable increments

Effort, deadlines, and diff size affect sequencing, not diagnosis. If the durable fix is larger, stage it; do not mislabel another exception as the final solution.

Completion criterion: explain why the selected depth is sufficient and why the next shallower depth would preserve the failure class.

When the selected repair changes dependency direction, application layers, presentation ownership, construction, or stateful lifetimes, also apply $architect-maintainable-apps to define the target architecture before migration.

4. Define the target structure

Before editing, specify:

• the single owner of the invariant;
• the stable interface exposed to callers;
• which differences are real domain variation and which are accidental duplication;
• the obsolete paths, flags, overrides, or branches to remove;
• a migration order that keeps the system runnable.

Prefer deleting states and relationships over adding coordination. Prefer data-driven variation over copied control flow. Preserve public behavior unless the user requested a behavior change.

Completion criterion: the target can be described without referencing the old patches.

5. Lock the invariant with tests

• Add or tighten the smallest behavior/geometry/contract test that fails for the root cause.
• Cover representative siblings or callers when the bug class spans more than one instance.
• Test both sides of boundary conditions and the state transition that previously failed.
• Avoid snapshots as the only evidence when a semantic or geometric invariant can be asserted directly.

Completion criterion: the test would also fail for a future reintroduction of the same patch stack.

6. Refactor through the owner

• Change the owner or boundary first.
• Migrate callers to the repaired contract.
• Remove superseded exceptions in the same change.
• Keep temporary adapters narrow, named, and scheduled for removal within the active task when feasible.
• Re-read the diff for newly introduced flags, duplicated logic, and compatibility branches.

A successful refactor may change more lines while leaving fewer concepts, branches, and special cases.

Completion criterion: the root invariant has one owner and no touched caller still depends on the obsolete repair path.

7. Validate the resulting system

Run targeted tests first, then type, lint, build, and broader regression tests proportional to risk. Inspect the final code rather than stopping when tests turn green.

Verify:

• the original symptom is gone;
• sibling cases obey the same invariant;
• obsolete patches are deleted;
• public contracts remain stable or migrations are complete;
• control flow and ownership are simpler to explain;
• no unrelated subsystem was pulled into the refactor.

Completion criterion: provide evidence for behavior and for structural simplification.

Report

State the violated invariant, selected repair depth, owner changed, patches removed, tests run, and any intentionally deferred migration. Call out a tactical workaround honestly if scope or authority prevents the durable repair.

Failure signals

Stop and reassess when:

• the proposed fix adds another boolean, selector override, route check, or timing delay;
• the same correction must be copied to a second location;
• a child compensates for its parent's incorrect contract;
• a compatibility layer has no removal condition;
• the refactor introduces a generic abstraction before two concrete policies are understood;
• tests pass only because assertions were weakened or snapshots replaced;
• the diff is small but the explanation of behavior becomes longer.