The budget page now shows two numbers that both answer "how much have I got left", computed from entirely different things, with nothing on the page relating them.
This is a design question rather than a defect, and it is not mine to settle — it decides what the budget is. Opening it rather than picking one quietly in a PR.
What is on the page today
app/views/budgets/show.html.erb renders both:
The allocation bar (budget_categories/_allocation_progress.erb) — "X left to allocate", from
def available_to_allocate
(budgeted_spending || 0) - allocated_spending
end
Plan minus plan. It never consults an account balance.
The cash panel (budgets/_available_cash.html.erb, behind the preview flag, added in #3179) — Available in cash / Already earmarked for goals / Really free, from
def free_cash
[ available_cash - earmarked_for_goals, 0 ].max
end
Real balances, minus what goals have claimed.
Why that is confusing
A reader with a 3,000 plan, 2,400 allocated, 8,000 in cash and 2,000 earmarked sees:
600 left to allocate
…
Really free 6,000
Both figures are correct. Neither is a bug. But nothing says they measure different things, and the one that governs the decision the reader is about to make — setting a category budget — is the smaller, less prominent one. The subtitle on the panel, "Beside the plan above, not part of it", is honest but defines the number by what it is not.
This is a maintainer's call
I am not going to pick one of these in a PR. The two options below lead to different products, and the difference is not a matter of taste I can settle from the code — it decides what a budget in this app is. Both are laid out with what they cost, so the decision can be made on the consequences rather than on the description.
I am happy to implement whichever is chosen, and I would rather rework than bolt the other behaviour onto the current shape.
Option 1 — Fold cash into the allocation arithmetic
The budget becomes YNAB's: you distribute money you hold, not money you expect. available_to_allocate stops meaning "what is left of my plan" and starts meaning "what is left of my balance".
What it gains. One number answers "how much have I got left", and it is the true one. The envelope metaphor becomes literal. It is what many people expect from an envelope budget, and the confusion in this issue disappears entirely rather than being explained away.
What it costs. It is a different product from the one that exists. budgeted_spending and expected_income are numbers the user types, and every figure on the page derives from them. Rollover (#3143), envelope moves (#3164) and the category bars all assume the forecast model — changing the meaning of available_to_allocate reaches all of them.
What it breaks for users. Anyone budgeting a month before the money arrives — salary on the 28th, plan on the 1st — can no longer allocate it. That is the intended behaviour of the model, but it is a real change for existing users who plan ahead, and it arrives without warning on an app they already use one way.
Scope. Large. Model change plus every consumer of the allocation pair, and a migration path for families mid-month.
Option 2 — Keep the forecast, name the relationship
The plan stays a plan. The cash panel gains a sentence tying the two together, or the two are nested visually so one plainly sits inside the other.
What it gains. Cheap, contained, and it keeps a model that several merged features already depend on. Nobody's existing workflow changes.
What it costs. The oddity stays: a user can allocate a plan their cash cannot cover, and the page shows both facts without drawing the line. It explains the confusion rather than removing it.
The follow-up question if this is chosen. Whether "really free" should be prominent at all, or belongs somewhere quieter than the budget page — the goals page, for instance, where the earmark subtraction it performs is inspectable. Right now it sits beside the allocation bar, which is what invites the comparison in the first place.
Scope. Small. Copy and layout, no model change.
Option 3 — Remove the cash panel
Worth naming rather than leaving implicit. The panel is behind the preview flag and could simply go, restoring a page with one unambiguous number.
What it costs. The question it answers — "how much of my money is actually free, after what my goals claim" — has no other home today, and it is a question people ask. Removing it is choosing not to answer it rather than answering it elsewhere.
What would help
Which option, or a fourth framing I have not seen. If option 2, also the follow-up question above.
The budget page now shows two numbers that both answer "how much have I got left", computed from entirely different things, with nothing on the page relating them.
This is a design question rather than a defect, and it is not mine to settle — it decides what the budget is. Opening it rather than picking one quietly in a PR.
What is on the page today
app/views/budgets/show.html.erbrenders both:The allocation bar (
budget_categories/_allocation_progress.erb) — "X left to allocate", fromPlan minus plan. It never consults an account balance.
The cash panel (
budgets/_available_cash.html.erb, behind the preview flag, added in #3179) — Available in cash / Already earmarked for goals / Really free, fromReal balances, minus what goals have claimed.
Why that is confusing
A reader with a 3,000 plan, 2,400 allocated, 8,000 in cash and 2,000 earmarked sees:
Both figures are correct. Neither is a bug. But nothing says they measure different things, and the one that governs the decision the reader is about to make — setting a category budget — is the smaller, less prominent one. The subtitle on the panel, "Beside the plan above, not part of it", is honest but defines the number by what it is not.
This is a maintainer's call
I am not going to pick one of these in a PR. The two options below lead to different products, and the difference is not a matter of taste I can settle from the code — it decides what a budget in this app is. Both are laid out with what they cost, so the decision can be made on the consequences rather than on the description.
I am happy to implement whichever is chosen, and I would rather rework than bolt the other behaviour onto the current shape.
Option 1 — Fold cash into the allocation arithmetic
The budget becomes YNAB's: you distribute money you hold, not money you expect.
available_to_allocatestops meaning "what is left of my plan" and starts meaning "what is left of my balance".What it gains. One number answers "how much have I got left", and it is the true one. The envelope metaphor becomes literal. It is what many people expect from an envelope budget, and the confusion in this issue disappears entirely rather than being explained away.
What it costs. It is a different product from the one that exists.
budgeted_spendingandexpected_incomeare numbers the user types, and every figure on the page derives from them. Rollover (#3143), envelope moves (#3164) and the category bars all assume the forecast model — changing the meaning ofavailable_to_allocatereaches all of them.What it breaks for users. Anyone budgeting a month before the money arrives — salary on the 28th, plan on the 1st — can no longer allocate it. That is the intended behaviour of the model, but it is a real change for existing users who plan ahead, and it arrives without warning on an app they already use one way.
Scope. Large. Model change plus every consumer of the allocation pair, and a migration path for families mid-month.
Option 2 — Keep the forecast, name the relationship
The plan stays a plan. The cash panel gains a sentence tying the two together, or the two are nested visually so one plainly sits inside the other.
What it gains. Cheap, contained, and it keeps a model that several merged features already depend on. Nobody's existing workflow changes.
What it costs. The oddity stays: a user can allocate a plan their cash cannot cover, and the page shows both facts without drawing the line. It explains the confusion rather than removing it.
The follow-up question if this is chosen. Whether "really free" should be prominent at all, or belongs somewhere quieter than the budget page — the goals page, for instance, where the earmark subtraction it performs is inspectable. Right now it sits beside the allocation bar, which is what invites the comparison in the first place.
Scope. Small. Copy and layout, no model change.
Option 3 — Remove the cash panel
Worth naming rather than leaving implicit. The panel is behind the preview flag and could simply go, restoring a page with one unambiguous number.
What it costs. The question it answers — "how much of my money is actually free, after what my goals claim" — has no other home today, and it is a question people ask. Removing it is choosing not to answer it rather than answering it elsewhere.
What would help
Which option, or a fourth framing I have not seen. If option 2, also the follow-up question above.