Strategic Change

Working code isn't enough. Each minimal patch adds a special case, a flag, or a dependency, and complexity grows one small change at a time. If you're not making the design better, you are probably making it worse.

Before editing

1. Read the design around the change: the module's interface, its callers, and the conventions in use.
2. Ask: if this module had been designed from scratch with this change in mind, what would it look like? Sketch that shape.
3. List where the current structure fights the change. Typical signs: you would need a new flag or boolean parameter, a parameter threaded through layers that don't use it, knowledge duplicated in a second module, or an if for one caller.

Choose the path

• Ideal: refactor toward the sketch, then make the change. Default to this when the refactor stays close to the code you're touching. Aim to spend about 10–20% extra effort on it.
• Nearly as clean: if the ideal is too costly, look for a variant that gets most of its benefit for a fraction of the work.
• Tactical, with debt recorded: only under a real constraint, such as a deadline or a cross-team incompatibility. Name the debt explicitly (a TODO with the reason, or an issue), never silently.

While editing