A build fails because a genuinely needed feature pushes a route's JavaScript over its size budget. What policy around bundle budgets keeps that failure useful, rather than something teams routinely override?

## What a budget is actually for A size budget does not make code smaller. It converts an invisible, gradual cost into a discrete event at a moment when someone still has options. Every kilobyte of page weight is added by someone who had a reason, and each addition is individually defensible; the harm is cumulative and shows up months later as a slow product nobody chose. The budget's function is to interrupt that drift with a decision point. This framing determines the policy. If the goal were prevention, overrides would be failures. Since the goal is a decision, overrides are fine — as long as they are decisions, made by someone accountable, and visible afterwards. ## The menu when it breaks A good policy tells the engineer who hit the wall what their options are, in rough order of preference: 1. **Defer it.** Move the new code off the initial payload so it loads on interaction or on navigation. Often the cheapest fix and usually the right one for features not everyone uses. 2. **Ship it lighter.** A smaller dependency, a narrower import, dropping a feature of the library that is not needed, or implementing the small piece actually required. 3. **Pay for it.** Remove or defer something of comparable weight from the same route. This is the option that keeps a fixed budget honest, and it is the one that quietly forces cleanup of things nobody would have prioritised otherwise. 4. **Raise the budget deliberately.** Sometimes the feature is worth the bytes. Then the increase is a real decision: separate change, named approver, stated reason, and ideally a note about what would let it come back down. What is not on the menu is editing the number inside the same commit that broke it. Done routinely, that turns the budget into a log of whatever shipped — it records history instead of constraining it, and reviewers stop reading the change because it always accompanies a feature they already approved. ## Hard fail versus warning Warn-only budgets are attractive because nothing gets blocked, and they almost always decay. A warning that appears in logs with no failing status competes for attention with everything else in a build log and loses; after a few releases it fires constantly and means nothing. Hard failure with a cheap, documented override is the more durable arrangement. The failure guarantees a human looks; the override guarantees the team is never actually stuck. What makes the override healthy is that it costs a small, visible action — a separate commit to a tracked file, an approval from whoever owns the number — rather than a flag someone can set in passing. The corollary is that override *frequency* is itself a metric worth watching. If the budget is raised most sprints, either the number was wrong or the product has genuinely changed shape; both are worth an explicit conversation. A budget nobody has ever hit is also suspicious — it is probably set above where the code is heading and constraining nothing. ## Ownership A budget with no owner is a budget that gets raised by whoever is most inconvenienced by it. Name someone — a tech lead, a performance working group, the team that owns that route — who approves increases. Their job is not to say no; it is to make sure the tradeoff was stated. That means the reason recorded alongside the new number should be readable a year later: what was added, why deferring or trimming was rejected, and what would make it reducible again. ## Anchor the number to something outside the build The strongest version of this policy connects the byte number to a user-facing goal: the route should be usable within a stated time on a stated device and connection, and the budget is the byte figure that supports it. Then raising the budget is not a build-tooling adjustment, it is a decision to spend part of a user-experience commitment on a feature — a conversation product people can participate in, with a cost stated in terms they care about. Without that anchor, a budget is an arbitrary number defended on principle, and arbitrary numbers lose arguments against concrete features every single time. With it, the question stops being "can we raise this?" and becomes "is this feature worth being that much slower for the people who use this screen?", which is the question the budget existed to force in the first place.