complexity-budget

When you change existing code, the cheap move is to add — a new flag, a new branch, a copy-paste, a parallel path — because adding needs no understanding of the rest of the code, while folding in does. That default is how codebases rot. Before you take the additive path, make it earn its place.

The rule: decide where the change belongs before you decide whether it's worth it, and settle both before the code exists — afterwards you will rationalize whatever you wrote.

Before you edit — four questions

Which layer owns this? Every question below optimizes on top of this one, so answer it first. The wrong layer is rarely the wrong idea; it's the layer that's easiest, the one that's most convenient, or the one already open in your context. Two tests: where is the invariant stated? — the fix belongs where the property it restores is established; and if your layer vanished, would the problem remain? — if yes it's below you, and you're patching a symptom. One countable signal: if N callers each need the same small fix, the behavior belongs beneath them.
Does it add a dimension, or just a point? First try to get the behavior by composing existing functions, types, or config — if that works, do that. If it doesn't, name a user-visible outcome that is reachable with the new thing and unreachable without it. No such outcome means it's a combination of what you already have: ship it as a preset, a recipe, or a doc, not as a new flag, branch, or abstraction.
Simple, or just easy? Easy = the edit closest to hand — familiar, local, no need to understand the rest of the system. Simple = the change that doesn't tangle two things that were separate. They're often not the same edit. Pick simple. A change that "felt small to write" can still tangle the system.
Fold in, or bolt on? Name both options out loud: fold the new case into an existing function, vs. add a parallel path next to it. Default to folding in — but only inside a trust boundary. Folding in trades duplication for coupling, and across an ownership, team, or dependency boundary that trade usually loses: copy the small thing instead. Bolt on when folding in would reach across such a boundary, or when it genuinely costs more.

Skip all four for a one-line fix, a typo, a string or config value, test data, or a pure deletion.

After you edit — read your own diff

Read the diff yourself — you can see all of this by eye. Check in order; the first two are what matter, and "a lot" is judged against a normal change in this repo, not in the abstract.