Insights feed and weekly Action Plan

After every scan we run two parallel passes over the new data:

1. Insights — detect movement in your visibility numbers and post it to the What changed timeline on Overview.
2. Actions — turn the gap each insight surfaces into one or more specific things you can do this week, rendered as cards in the Actions tab.

Insights say what happened. Actions say what to do about it. They share the same scan data but live in different parts of the dashboard on purpose — readers and doers move at different paces.

The five insight types

Every insight is one of:

Type	When it fires
visibility_gap	A monitored query has zero mentions across all engines in the latest scan, but had ≥1 in a recent prior scan.
competitor_displacement	An answer that previously cited you now cites a tracked competitor and not you, on the same query.
trend_drop	Mention rate or GEO Score fell sharply between consecutive snapshots (threshold scales with sample size — see below).
trend_recovery	The opposite — score climbed sharply after a recent drop. Posted only when a trend_drop was active.
repeated_absence	The same query has been "not mentioned" for 3+ consecutive scans — a chronic gap, worth its own action.

Each insight stores the trigger conditions, the affected query (or queries), and a short human-readable headline. Click any timeline entry to jump to the relevant Actions row.

Sample-aware thresholds

If you only track 5 queries, a single result swing represents 20 % of your visibility — a trend_drop triggered on a 10pp threshold would fire constantly on noise. The thresholds scale with your sample size:

Tracked queries	trend_drop threshold	trend_recovery threshold
< 10	30 percentage points	25 pp
10–19	25 pp	20 pp
≥ 20	20 pp	15 pp

So a Pro user with 15 monitored questions sees a trend_drop only when GEO Score moves at least 25 pp between scans; a Business user with 40 questions sees it on a 20 pp move. The math is in lib/scan/insights/.

Decay rules — what stays unread

Three rules keep the timeline from filling with stale or contradictory entries:

1. Contradictory pair dedup. When a new trend_drop fires, any unread trend_recovery from the previous 24 hours is auto-dismissed (and vice-versa). The inbox always reflects the current direction, not back-and-forth swings.
2. Stale unread collapse. Insights older than 14 days that you haven't marked read move into an Older unread section that collapses by default. Forgetting to dismiss a 3-week-old alert doesn't crowd out fresh signal.
3. Single source of truth. Each insight links to its corresponding Action card via View action plan →. The two views never disagree.

Action cards — six kinds

Each action is one of six deterministic templates the Action Engine v0 emits:

Kind	When it's generated	What it asks you to do
add_to_listicle	Query where you're not mentioned but ≥2 competitors are cited as a roundup.	Pitch yourself for inclusion in the cited listicle pages or publish your own competitor comparison.
add_social_proof	Query where you're mentioned with weak quality (mentioned, not recommended).	Ship a customer story, case study, or G2-style proof point that AI engines can find.
sharpen_differentiator	Repeated absence on a query you'd expect to win — your positioning isn't reaching AI.	Rewrite the homepage / feature page hero to lean into the differentiator the question is asking about.
add_faq_schema	Question-shaped query (how/what/why/when…) where you have a relevant page but no FAQPage JSON-LD.	Use the FAQ schema generator on the relevant page and publish.
reinforce_brand_token	You're mentioned but as a domain-only citation (no brand name in prose).	Ensure your brand name (not just URL) appears in titles, metadata, and the first paragraph of cited pages.
improve_page_readiness	Discovery Readiness score below 70 on a page that ranks for at least one monitored query.	Open the page-health drawer (we deep-link straight to it) and fix the highest-impact issues — bad meta description, missing JSON-LD, weak heading flow.

Each card carries:

• Title — short imperative ("Add JSON-LD to /pricing").
• Why — one sentence connecting the gap to the data ("Query X has been not_mentioned 3 weeks running and your competitor is in the top citation.").
• Impact level (high / medium / low) for sorting.
• Trigger — the originating scan + query, so you can drill back into Reports.
• Deep link — a direct URL into the right page-health drawer or JSON-LD generator dialog where applicable.

The cadence

Insights and actions are recomputed at the end of every scan (manual, pulse, or deep). The Overview What changed feed shows the last 30 days; the Actions tab shows the currently-active items (unresolved + not auto-dismissed by decay rules above).

When you mark an action done (or hide it), the system stops surfacing it for that specific query/scan combination — but if the underlying gap reappears in a future scan, the action regenerates.

Honest limits

Read further

• GEO Score — what the trend deltas actually measure.
• Competitor tracking — how competitor_displacement insights pick the rival to call out.
• Content audit — where the improve_page_readiness action sources its readiness scores.