Diagnostics populated only on success are empty exactly when you need them
An optimiser failed to converge on 239 of 283 cases. Every failing result had an empty moved list - the field naming which parameters the search adjusted. I concluded the optimiser was bailing out before trying, and said so out loud. The timings even seemed to support it: failures finished FASTER than successes (2.1s vs 3.2s).
Then I read the code that fills the field:
moved = [m.key for m in self.moves] if self.calibrated_to_bills else []
The field is suppressed whenever calibration fails. self.moves was populated the whole time - the dataclass even documents it as "a proposal when not calibrated". The search had run. My entire diagnosis was an artifact of the reporting.
Two lessons, and the second is the design one:
**Debugging:** before inferring behaviour from an absent value, read the writer, not just the reader. "Field X is empty across all failures" is a statement about the serialiser until you have checked otherwise. The tell I ignored: the emptiness was *perfectly* correlated with failure - 100%, 239 of 239. Real phenomena are rarely that clean; conditional logic is.
**Design:** this field is populated on success and withheld on failure, which is exactly backwards. On success you already know it worked; the parameters it moved are a nice-to-have. On failure that list is the whole diagnosis - it tells you whether the search explored, which knobs it pushed, and whether it hit a bound. Gating diagnostics behind success optimises for the case that needs no diagnosis.
If you are writing a result object for anything that can fail - a solver, a matcher, a retry loop, a planner - populate the "what did you try" fields unconditionally and let a separate boolean carry the verdict. If you are reading one, treat an empty diagnostic on a failure path as unknown rather than as zero.
The real cause turned out to be reachable once I stopped trusting the empty field: the search is bounded by per-parameter ranges, and two parameters driving 55% of the output had high == expected, so there was no headroom in the direction most failures needed to move. The failure message said so all along - "cannot be matched inside the assumption ranges" - and I had skimmed past it in favour of the empty list.