How insights work
Every insight is produced by a deterministic detector you can audit, or by an optional AI layer that is clearly labelled as such. This page documents the exact thresholds, so you can tell whether an insight is real before you act on it.
Four layers run in order, cheapest and most certain first, and each is told what the previous ones already found so nothing is reported twice:
- Detectors over your own telemetry - the five rule detectors documented below, reading the events our snippet collected.
- Detectors over connector signals - the same idea applied to every source you connected: missing security headers, open dependency alerts, failing Lighthouse audits, CI failure rate, subscription churn. Findings a source already judged are carried through in its own words rather than reworded by us.
- The AI pass over your telemetry - cross-signal patterns in the browser data the rules cannot express.
- The strategist - the only layer that sees every source at once. This is where a recommendation can join two of them, and where genuinely new ideas belong.
So the domains an insight can land in are wider than the frontend: product, ux, ui, performance, bug, functional, security, pricing, growth, code, seo, a11y, reliability, idea. Which ones you actually see depends on what you have connected - with the snippet alone you get the frontend set.
The analysis window and cadence
- Every rule detector looks at a rolling 7 day window. Nothing older influences an insight.
- A run covers every project that received events in the last 7 days. On the hosted instance that happens roughly every 6 hours (an in-process scheduler, plus an optional external cron hitting /api/cron/insights). Free is guaranteed weekly runs and Pro daily runs; in practice both are refreshed on the shared schedule.
- Generate now on the Insights tab runs the engine against your project immediately. It is limited to 5 manual runs per 10 minutes per account.
The five telemetry detectors
These read the events our snippet collects. Each reports at most 10 findings per run. The thresholds a connected source applies are the source's own and are documented on the connections page.
Rage clicks
The SDK emits a rage_click when the same element descriptor is clicked 3 times with less than 700ms between consecutive clicks. The detector groups those events by element and path, and only reports a group seen in at least 2 distinct sessions.
- Severity
- 3 (high) at 10 or more sessions, 2 at 5 or more, otherwise 1.
- Rank score
- sessions x 3 + total rage clicks
- Fingerprint
- rage:<path>:<selector>
How to read it: Something looks broken, responds too slowly, or gives no feedback. Check the loading and disabled states of that control.
Dead clicks
The SDK watches every click on an a, button, [role=button] or [onclick] element (native form controls are excluded to avoid false positives) and waits 800ms. If the URL did not change, no nodes were added or removed anywhere, no attribute changed on the element or its ancestors, and the tab was still visible, it emits a dead_click. The detector groups by element and path and needs at least 3 distinct sessions.
- Severity
- 3 at 10 or more sessions, otherwise 2.
- Rank score
- sessions x 3 + total dead clicks
- Fingerprint
- dead:<path>:<selector>
How to read it: Either the handler is broken, or the element should not look clickable. This is the detector that catches silently failing buttons.
JS error clusters
window.onerror and unhandledrejection events, grouped by message across the window. Resource load failures (missing images, blocked scripts) are recorded but excluded from this detector. The top 10 groups by session reach are reported.
- Severity
- 3 at 5 or more affected sessions, 2 at 2 or more, otherwise 1.
- Rank score
- sessions x 5 + occurrences
- Fingerprint
- err:<first 120 chars of the message>
How to read it: Ranked by how many real people hit it, not by raw count - one loop firing 5000 times in a single session ranks below an error touching 20 sessions.
Slow pages
LCP and INP samples are grouped per path and reduced to a p75. A path needs at least 5 samples for that metric. LCP is reported at 2500ms and above, INP at 200ms and above.
- Severity
- 3 when the p75 crosses Google's poor threshold (LCP 4000ms, INP 500ms), otherwise 2 for needs-improvement.
- Rank score
- 30 when poor, 15 when needs-improvement, plus samples / 10
- Fingerprint
- slow:<path>:<LCP|INP>
How to read it: LCP findings point at hero image weight, render-blocking scripts, and server response time. INP findings point at long tasks blocking the main thread during interaction.
Bounce-heavy entry pages
Sessions are bucketed by their first pageview. An entry page needs at least 10 sessions in the window, and is reported when 70% or more of those sessions viewed nothing else.
- Severity
- 3 at a bounce rate of 85% or more, otherwise 2.
- Rank score
- sessions x bounce rate
- Fingerprint
- bounce:<path>
How to read it: Either the page does not deliver what visitors expected, or the next step is not obvious. Weighted by traffic, so your busiest dead end sorts first.
The AI layer
When the instance is configured with an Anthropic API key, a second pass looks at the week in aggregate - traffic, top pages, web vitals p75, top error clusters, and the rule findings themselves - and is asked for patterns the rules cannot see: cross-signal correlations, prioritization advice, funnel observations. It is capped at 5 items per run, it is instructed never to restate a rule finding, and it returns nothing when the data is too thin.
A second AI layer, the strategist, runs only once you have connected a source. It sees your telemetry and every connected source together, which is the only vantage point some findings exist from at all - that a checkout error cluster and a churn spike are one incident, or that the plan nobody buys is the one your pricing page puts first. It is capped at 6 items and at most 2 of them may be a new idea, each traceable to a specific observation.
These insights are tagged source: ai in the API and shown as AI in the dashboard. Treat them as hypotheses with evidence attached, not as measurements. If the instance has no Anthropic key configured, both layers are skipped and you get deterministic insights only.
Two limits exist because an AI layer will always produce something plausible. AI insights are deduplicated by content rather than by the id the model gives them - it paraphrases its own ids between runs, and without this one observation arrived as a new insight every run until the feed was mostly restatements of itself. And they are capped at 12 per project: beyond that the marginal fifth version of an idea pushes out the measured defect underneath it. Deterministic findings are never deduplicated away or capped, because each one is a specific measurement.
Anatomy of an insight
| Field | Meaning |
|---|---|
| category | One of product, ux, ui, performance, bug, functional. Rule detectors always use the category listed above; the AI layer may use any of the six. |
| severity | 1 low, 2 medium, 3 high. Driven by reach, not by the kind of problem. |
| evidence | The raw numbers the finding rests on: selector, session counts, occurrence counts, p75 values, bounce rate, window length. If evidence looks wrong, the insight is wrong. |
| path | The affected page, or null for site-wide findings such as an error cluster spanning many pages. |
| score | Ranking number, comparable only within a project. The feed and the API sort by score descending, then by newest. |
| source | rules or ai. |
Dedup and the status lifecycle
Every finding carries a fingerprint that identifies the underlying problem rather than its wording. Re-running the engine updates the existing insight in place instead of creating a duplicate, so severity, evidence, and score stay current while your status and history survive.
| Status | Meaning and behaviour on the next run |
|---|---|
| new | Fresh finding. Only new insights are pushed to Slack, and it is the default filter for the API and MCP. |
| ack | Seen and accepted. Stays out of the new queue, keeps updating with fresh evidence. |
| done | Fixed. If the same fingerprint is detected again it is reopened as new and re-notified - that is your regression alarm. |
| dismissed | Not a problem, do not tell me again. Stays suppressed even while the signal keeps firing, and is never reopened. |
Because the window is a rolling 7 days, an insight whose signal stops appearing simply stops being updated. It is not deleted, so the feed doubles as a record of what you fixed.
Why the feed can be empty
- Not enough traffic yet. Every detector has a session or sample floor to avoid noise.
- Rage and dead clicks need repetition across different sessions - a single frustrated tester will not trigger them.
- Web vitals within Google's good range are never reported.
- Genuinely nothing is broken. That is a valid result.
Want to see a populated feed before you install anything? The live demo dashboard runs the real engine over generated traffic.