refactoring-principles

Refactoring — Cross-Language Principles

This skill defines the abstract rules. Language-specific examples live in:

• php-refactoring (PHP / Symfony)
• ts-refactoring (TypeScript / Node)
• (others as they join the stack)

1. Trace the Complete Business Flow BEFORE Refactoring

A local refactoring that ignores the global flow produces incomplete abstractions. Before touching any code, trace the data flow end-to-end.

Process:

1. Identify all inputs: form, API, database, file system, etc.
2. Trace each piece of data from source to final destination.
3. Spot convergence points (same object, different sources).
4. Design the abstraction that covers ALL paths.

Criterion: if an object can be constructed from N different sources, the refactoring must identify all of them before defining the structure.

2. Design by Tracing All Consumers (Consumer-Driven Value Objects)

When creating or modifying a value object, list all its consumers to define the required properties. Do not limit the analysis to the creation point.

Process:

1. List every place that CONSUMES the object.
2. For each consumer, note the data it needs.
3. Include in the object everything consumers extract.

Criterion: a value object is complete when no consumer needs an external mapping to interpret it.

Before considering the value object "done", re-check it against every creation point too:

1. List all creation points (where is it constructed?).
2. List all consumers (where is it used?).
3. For each consumer, what data does it extract?
4. Include ALL extracted data as properties.
5. If a consumer needs an external mapping → missing property.

3. Imports as a Coupling Signal

A file's imports reveal its real dependencies. After a refactoring, verify that remaining imports are consistent with the class's responsibility.

Post-refactoring check:

1. List the imports of the modified file.
2. Does each import belong to this class's layer/responsibility?
3. A "foreign" import signals misplaced responsibility — move the code.

Criterion: if a file imports a type that does not match its layer/responsibility, code needs to be moved.

4. The Deletion Test (Is an Abstraction Earning Its Keep?)

Before keeping a wrapper, layer, or indirection, imagine deleting it and inlining it into its callers.

Process:

1. Mentally delete the module and inline it at every call site.
2. If the complexity vanishes, it was a pass-through — delete it for real.
3. If the same complexity reappears duplicated across N callers, it was earning its keep.

Criterion: an abstraction justifies its existence only when removing it would duplicate real complexity across callers — not when it merely renames a single indirection.

Exemption: a seam mandated by the project's layered architecture (e.g. a mapper enforcing the domain/infrastructure boundary) is exempt from this test — it earns its keep by enforcing the dependency direction, not by hiding complexity.

5. Pin Unpinned Behaviour First

When the refactoring must preserve an observable behaviour no existing test pins, set up a characterization net before touching the code: see craft:testing-principles §16.

Quick Reference

Rule	Principle
Complete business flow	Trace all sources and destinations before refactoring
Trace consumers	List all usages to define a value object's structure
Imports = coupling	Imports reveal dependencies; verify their consistency
Complete value objects	Include everything consumers need; no external mappings
Pin first	Unpinned behaviour gets a characterization net before the refactoring (craft:testing-principles §16)
Deletion test	An abstraction earns its keep only if deleting it duplicates complexity across callers