fix(findings): a capped promise is info unless the capped insight still ends weak

insight_promise_capped was a warning in the Slack count on every build where
the tuning loop capped a promise to what a bounded measure's band can
deliver. Two of the five lines on Frontline's second replay (fe431f93cbf8,
2026-10-20) were caps that had worked: the rows were pushed as far as the
band allows and the chart shows that honestly. The only "fix" is a blueprint
knob, not something an SE can act on.

boone, 2026-10-20: info severity, "keeping it a warning only when the capped
insight also ends weak". The record is now built once the loop is over, from
the insight itself (authored vs driven magnitude), so its severity can read
the final validation: info, or warning with "still ended weaker" appended
when the insight is in the final failed set. Slack skips info records, so a
cap that worked leaves the warning count the way the unclassified roll-up did.

Tests: test_a_capped_promise_is_info_unless_the_insight_still_ends_weak
(Spendflo fixture: info; scripted still-weak: warning). Suite 1423 passed,
3 pre-existing failures.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

demoprep_app/pipeline/build_demo.py

@@ -288,20 +288,12 @@ def build_demo(
         for note in _boost_weak_insights(blueprint, report):
             progress(f"insight promise capped: {note}")
             warnings.append(f"insight promise capped: {note}")
-            findings.append(Finding(
-                code="insight_promise_capped",
-                severity="warning",
-                stage="generation",
-                message=note,
-                suggestion=(
-                    "if the original lift is the point of the story, widen the measure's declared "
-                    "band (params.low/high) or plant it on a measure that is not bounded; "
-                    "otherwise the capped promise is what the chart can honestly show"
-                ),
-            ))
 
     findings.extend(round_findings)
     warnings.extend(round_warnings)
+    # Capped promises are recorded once the loop is over, because their
+    # severity depends on how the capped insight ENDED (see the helper).
+    findings.extend(_capped_promise_findings(blueprint, report))
     if report is not None and report.failed_insights():
         warnings.append(
             "Some planted insights are weaker than promised after tuning (or could not be "
@@ -427,6 +419,52 @@ def _generate_with_formula_repair(
     )
 
 
+def _promise_was_capped(insight) -> bool:
+    """True when tuning LOWERED this insight's magnitude toward 1.0 — a band
+    cap. A boost moves it the other way, and the laggard floor keeps it beyond
+    the authored figure, so neither reads as a cap."""
+    authored = insight.authored_magnitude
+    return authored is not None and abs(insight.magnitude - 1.0) < abs(authored - 1.0) - 1e-9
+
+
+def _capped_promise_findings(blueprint: DemoBlueprint, report: ValidationReport | None) -> list[Finding]:
+    """One record per capped promise, decided once the tuning loop is over.
+
+    A cap is an action that worked: the rows were pushed as far as the band
+    allows and the chart shows that honestly. So the record is `info` — kept
+    on the run, out of the Slack count — unless the capped insight is STILL
+    weak at the end, when the SE has a decision to make (boone, 2026-10-20:
+    "a warning only when the capped insight also ends weak"). Two of the five
+    lines on Frontline's second replay (fe431f93cbf8) were caps that had
+    worked.
+    """
+    weak = {c.insight_id for c in report.failed_insights()} if report is not None else set()
+    out: list[Finding] = []
+    for insight in blueprint.insights:
+        if not _promise_was_capped(insight):
+            continue
+        still_weak = insight.id in weak
+        out.append(Finding(
+            code="insight_promise_capped",
+            severity="warning" if still_weak else "info",
+            stage="generation",
+            message=(
+                f"insight {insight.id} promised {insight.authored_magnitude:g}x on {insight.measure}, "
+                f"whose band can deliver at most {insight.magnitude:.2f}x — promise capped at "
+                f"{insight.magnitude:.2f}x and the rows pushed further in the band instead"
+                + ("; the chart still ended weaker than the capped promise" if still_weak else "")
+            ),
+            suggestion=(
+                "if the original lift is the point of the story, widen the measure's declared "
+                "band (params.low/high) or plant it on a measure that is not bounded; "
+                "otherwise the capped promise is what the chart can honestly show"
+            ),
+            extra={"insight_id": insight.id, "promised": insight.authored_magnitude,
+                   "capped_at": insight.magnitude, "still_weak": still_weak},
+        ))
+    return out
+
+
 def _tuning_stalled(previous: dict[str, float], current: dict[str, float]) -> bool:
     """True when every weak insight both rounds measured realized the same
     ratio — the last boost changed nothing, so the next one will not either."""

tests/test_build_abort_policy.py

@@ -1397,7 +1397,7 @@ def test_tuning_stops_when_a_round_changed_nothing():
     assert not _tuning_stalled({"i1": 1.12}, {"i3": 1.12})          # nothing in common: not a stall
     src = inspect_source(build_demo_module.build_demo)
     assert "_tuning_stalled(previous_observed, observed_now)" in src
-    assert 'code="insight_promise_capped"' in src
+    assert "_capped_promise_findings(blueprint, report)" in src
 
 
 def inspect_source(fn):

tests/test_tuning_round_findings.py

@@ -186,3 +186,30 @@ def test_distinct_messages_for_one_measure_are_still_distinct_findings():
     low = Finding(message="97/3333 row(s) sit ON the low bound", **common)
 
     assert _dedupe([high, low, high]) == [high, low]
+
+
+def test_a_capped_promise_is_info_unless_the_insight_still_ends_weak(monkeypatch):
+    """boone, 2026-10-20: a cap is an action that worked, and its only fix is a
+    blueprint knob, so it leaves the Slack count — unless the capped insight is
+    still weak when tuning ends."""
+    build = _build(monkeypatch, [])
+    capped = [f for f in build.findings if f.code == "insight_promise_capped"]
+    assert [f.extra["insight_id"] for f in capped] == ["i2"]         # the bounded rate's 1.5x promise
+    assert capped[0].severity == "info" and capped[0].extra["still_weak"] is False
+    text = format_build_findings(prospect="Spendflo", se_email="x@thoughtspot.com",
+                                 findings=build.findings, run_id="r")
+    assert "insight_promise_capped" not in (text or "")
+
+    # Scripted: the same cap, but i2 never realizes -> the record is a warning.
+    def validate_with_i2_weak(blueprint, bundle):
+        report = validate_bundle(blueprint, bundle)
+        for c in report.insight_checks:
+            if c.insight_id == "i2":
+                c.passed = False
+        return report
+
+    monkeypatch.setattr(build_demo_module, "validate_bundle", validate_with_i2_weak)
+    build = _build(monkeypatch, [])
+    (capped,) = [f for f in build.findings if f.code == "insight_promise_capped"]
+    assert capped.severity == "warning" and capped.extra["still_weak"] is True
+    assert "still ended weaker" in capped.message