From 03c26cc21a1f9202760a3ff57c505bc391e808cc Mon Sep 17 00:00:00 2001 From: Amirhossein Khalili Date: Thu, 20 Aug 2026 17:40:07 +0330 Subject: [PATCH] docs(analytics): approve actionable insight thresholds --- docs/ANALYTICS-SPEC.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/ANALYTICS-SPEC.md b/docs/ANALYTICS-SPEC.md index 8753cf0..ca7bb27 100644 --- a/docs/ANALYTICS-SPEC.md +++ b/docs/ANALYTICS-SPEC.md @@ -1,6 +1,6 @@ # Analytics Engine Capability Spec -- Status: Draft — not approved for implementation +- Status: Approved specification — implementation not yet authorized - Capability: Analytics engine - Depends on: Approved Data Foundation specification - Last updated: 2026-08-20 @@ -109,6 +109,14 @@ Every section uses a versioned typed contract and has independent `queued`, `cal - Section publication is atomic; partial/failed calculations never overwrite a valid ready cache entry. - Database, Redis, queue, timeout, and authorization errors are distinguishable internally while merchant-facing errors remain safe and actionable. +## Actionable insight threshold + +- A deterministic actionable insight is eligible only when its comparison contains at least 100 relevant payment sessions. +- Rate insights require an absolute change of at least 3 percentage points. Amount and count insights require an absolute relative change of at least 20 percent. +- The threshold is a display eligibility rule, not a change to the underlying metric. Exact metrics and comparisons remain available even when no insight card is emitted. +- A zero, missing, or undefined baseline cannot produce a relative-change insight. Return the metric and an explicit unavailable comparison instead of dividing by zero or inventing a trend. +- Meeting a threshold does not prove causation. Insight language describes the observed change and a possible merchant action without claiming why it happened. + ## Observability - Measure section queue delay, calculation duration, query duration, cache hit/miss, retry count, failure class, SSE delivery/reconnect, and suppression rate. @@ -149,7 +157,8 @@ Every section uses a versioned typed contract and has independent `queued`, `cal - Compare with the immediately previous equivalent complete period. If it is empty or unavailable, return an explicit unavailable comparison rather than silently substituting another baseline. - Overview priority is bank-paid amount, bank-paid session count, payment success rate, then verification completion. Retry, timing, and fee analysis follow below. - MVP read-only drill-downs cover unverified-paid, failed, and retried sessions; payer tokens and peer-level rows are excluded. +- Actionable insight cards require at least 100 relevant sessions and either a 3-percentage-point rate change or a 20-percent amount/count change. Below-threshold comparisons remain visible as metrics but do not generate an action claim. -## Open product decisions +## Open product decisions before implementation planning -- Deterministic threshold/severity rules for surfacing actionable findings +- None. Any new or changed metric, period, cohort, threshold, or cross-service contract requires a specification amendment before implementation.