Diagnostic "why" narration on Clarity's trend card

The original whole-screen Summary narration card was replaced with a scoped "why" on the Insights Trend card, computed by a deterministic engine (trend-why) that decomposes a revenue or margin move into volume, price, and mix effects that sum exactly to the change, plus the treatments driving it. The model's only job is to reword an already-computed diagnosis; it never selects a cause, a number, a severity, or a link.

From numbers to a diagnosis

The whole-screen Summary card it replaced had two earlier, narrower fixes: a card-collapse and a payout-concentration/receivables callout for unbuilt sections, and a fix to stop feeding the model unrounded decimals so it quoted whole numbers instead of figures like "24.64640%". Neither addressed the deeper problem, which the nightly eval's own scores made visible: narrations read well (tone ~3.6 to 4.1 out of 5) but were not useful (~2.5 to 2.9 out of 5), "well-phrased filler."

The feature went through three passes in quick succession. The first version surfaced raw field names and mismatched units, reading like a debug dump: it named engine internals ("mix effect", "volume effect"), left ₹ amounts unformatted, and stated a margin percentage and a margin ₹ change as if they were the same measure. It was rewritten so the engine owns both the story and its wording: typed drivers carry an owner-language label, a was-to-now value, and a target section, with a simplified narrative naming the dominant cause plus at most one offsetting counterweight, and margin's two axes (profitability percentage and net ₹) reconciled and labelled separately. The final pass turned this into a real diagnosis: per-metric severity (ok, watch, act) computed by the engine and never by the model, a data-quality flag that catches an empty period or an implausible price before it reads as a business collapse, a primary cause with a confidence level (a volume count is exact; a mix share is an approximate residual and is hedged as such), per-treatment cost-versus-price attribution for margin causes, a suggested check, and a link to the specific treatment driving the move. Common, crisp cases render from a deterministic template with no model call at all; only nuanced or conflicting cases reach the model.

Faithfulness stays sign-sensitive

A 2026-09-01 eval run found the narration describing a month-over-month decline (stored as a signed negative value) as a positive magnitude, which the faithfulness gate correctly rejected since it checks signed values, not magnitudes. The fix was prompt-side: the model is now told to quote signed fields with their sign and never restate a decline as a bare magnitude. The gate's sign-sensitivity was left unchanged; only the trend-why gate specifically tolerates magnitude over sign, since that narration conveys direction in words.

See deterministic narration and the eval suite.