Idea: human-readable "why" tooltips on the plan table

[chalfontchubby]

A lot of the issues raised here (and honestly, a lot of the time I've spent digging through plan.py myself recently, e.g. #4231/#4272) boil down to "why did the plan charge/hold/export at this slot?" Answering that today means reading the optimizer passes by hand — not something we should expect from non-technical end users.

Idea for a v1: add a title=/hover tooltip on each plan-table cell with a short plain-English sentence explaining that slot's state — e.g. "Charging to 80% because the import rate this slot (8p/kWh) is low enough to be worth it before a more expensive period" or "Holding — already predicted to be above the 60% target this window."

Scoping it deliberately small to start:

• Derived entirely from data already computed at publish time in publish_html_plan() (output.py) — reusing the exact decision tree that already picks the slot's Chrg/HoldChrg/FrzChrg/Exp/HoldExp/FrzExp state, just narrating it instead of discarding the reasoning once the HTML arrow is written. No changes to the optimizer itself for v1.
• Two-tier: a confident sentence for the well-understood cases, falling back to the raw numbers (target %, predicted %, rates) rather than a vague sentence when a case doesn't cleanly fit a template.
• Gated behind a new expert-mode switch (off by default) so it's a zero-cost no-op for anyone who doesn't want it — this only touches per-row string building at publish time (~96 rows/cycle), not the optimizer's internal scenario search.

A harder v2 (explaining cross-window tradeoffs — "why this window and not that one") would need to reach into optimise_swap_charge/optimise_swap_export and thread a reason through a couple of window-merge points — more invasive, and out of scope for a first pass.

Wanted to float this before sinking time into it — does this seem like a worthwhile direction, and any strong opinions on the UX (tooltip vs. an expandable row vs. something else) or on what "confidently explainable" should cover for v1?

[farfromexact]

This is a strong low-risk v1 because it explains the decision at the point where the HTML plan is already being rendered. I would avoid reconstructing the optimizer logic a second time, though. A better shape is for the publish step to produce a small structured reason object or reason code alongside Chrg, HoldChrg, FrzChrg, Exp, and the other states, then render both the human sentence and the raw values from that same object.

A few details would make the feature robust:

• include the target, predicted state of charge, import or export rate, and relevant time window as parameters rather than interpolating hidden globals
• fall back to a factual numeric explanation when confidence is low
• keep the expert switch from changing the actual plan or optimizer output
• expose a machine-readable reason code for debugging and regression tests
• use an accessible disclosure or focusable explanation on mobile, not only a hover title attribute

For v1, the per-cell reason is a good scope. The cross-window explanation should remain separate because it needs provenance through the merge passes. A handful of fixed optimizer fixtures covering charge, hold, export, freeze, and fallback cases would give you a stable contract before touching the UI wording.

[chalfontchubby]

Thank you for taking the time to write such a thoughtful and detailed review — it's genuinely appreciated, and it made the feature better.

A few updates since your comment:

• Reason code + structured object: done. reason still renders as the same sentence, but each contributing decision (state + any manual override) is now also captured as a separate structured entry — a stable reason_code (e.g. charge_low_rate, freeze_export_below_threshold, manual_override) plus the raw values that drove it (rate, threshold, target %), kept independent of the wording. So the sentence and the numbers behind it can now be tested and consumed separately, as you suggested.
• Not reconstructing optimizer logic: confirmed, and kept that way through the change above — everything is still captured inline at the exact point the state is decided, nothing gets re-derived in a second pass.
• Cross-window (v2) scoping: agreed and staying out of this pass, for the reasons you gave — the window-merge provenance issues make it a meaningfully bigger piece of work on its own.
• Mobile/touch: you're right that a hover-only title= attribute doesn't serve touch devices at all. Rather than block this pass on it, I'd like to treat it as a fast-follow (1.1) rather than in-scope here — the plan data and the rendering are already cleanly separated, so a tap-friendly disclosure can be layered on without touching the data side. Happy to hear if you think that sequencing is wrong.

Thanks again — this kind of review is exactly what makes a feature like this solid before it ships.

Put a draft PR up with the current state, mainly so there's something concrete to react to rather than just prose — very much a strawman at this point, not presented as final: #4311. Comments on the actual wording/shape welcome there.