An insight has to name something the reader can do, or it is a chart with a sentence on top. Impressions fell last week is a chart. Twelve queries sitting between position eight and twenty with below-average click-through, so rewriting their titles is the obvious change to make this week, is an insight: it names the entity, the measurement and the action in one breath. The way to make that stick in software is to make the action a required field, so a rule that cannot fill it cannot ship.
An insight in this product is a record with a fixed shape, and the shape is the argument. Each finding carries a headline in active voice naming the thing and the number, two or three sentences of detail, a recommendation, the evidence rows behind it, a score, the window it looked at and the entity it is about. The recommendation is not optional and that is the whole design: a rule that cannot say what to do is not producing insights, it is producing commentary.
| Field | What it holds | Why it is there |
|---|---|---|
| headline | One sentence naming the thing and the number | So the finding is readable without the chart |
| detail | Two or three sentences | What is happening and why it matters |
| recommendation | What to do about it | Required — a rule that cannot fill it does not belong |
| evidence | The measurements behind the sentence | So a reader can ask where that number came from |
| score | A sort key from 0 to 100 | The order across every source |
| id | Rule name plus the entity, never the date | So last week's problem is recognisable as the same one |
Severity and rank are different jobs, and conflating them is how a report ends up leading with a critical finding about a page with almost no traffic. Severity is the label a reader sees — critical, high, medium, low — and it answers how much of their attention the finding deserves. The score is the sort key, a number from 0 to 100 that ranks findings across every source at once, and the house formula behind it is reach multiplied by confidence multiplied by headroom, normalised. Findings are ordered by score, with severity used only to break ties so that the label stays honest.
The fifth kind is there for a reason that is easy to skip. Opportunity, risk, anomaly and health are all forms of complaint, and a product that only ever tells a founder what is wrong teaches them nothing they can repeat. A win — something that improved — is shipped so that a person who is never told what worked can be told what worked.
First click, linear, time decay and position-based were withdrawn in November 2023. What remains in the GA4 attribution reports is data-driven, paid and organic last click, and Google paid channels last click — and one of the three is still the one arguments end on.
Market4 turns one release note into a changelog page, a blog post, a mail-out and a week of social posts — and then tells you which of them brought anyone back.
Handing analytics rows to a language model and printing what comes back is the obvious implementation, and it fails on three counts that all bite the same way. An inference that moves somebody's money has to be reproducible, so two people looking at the same week must read the same sentence and a regression in that sentence has to be catchable by a test. Every number in a finding has to be traceable to the row it came from, which is what the evidence array is for. And a model asked to comment on a thin table will invent a number, while thin tables are the normal case for a new site.
Being rule-shaped has a second benefit that shows up in the test suite rather than the interface. A rule takes already-fetched data and returns findings, doing no input or output of its own, so it can be tested against a fixture and a whole pack of rules costs exactly one round trip to the API no matter how many rules it contains.
A report that produced no findings has to distinguish between two very different situations, and one field does it. Alongside the findings, a report carries a list of the rules that produced nothing and the reason each one was skipped, because found nothing and could not look are different answers and they look identical in an empty interface. The second one is the reader's cue to connect something or wait for data, which is an action, which makes it an insight in its own right.
An insight names an action the reader can take in a tool they have. Impressions fell is a metric with a direction attached; twelve queries at position eight to twenty with below-average click-through, whose titles could be rewritten this week, names the entity, the measurement and the next step. A practical way to enforce it is to make the recommendation a required field, so a rule that cannot fill it never reaches the reader.
No. An id built from the date makes every run produce brand-new findings, so the interface cannot tell a reader this is the same problem as last week, and dismissing something has no lasting effect. Build the id from the rule name plus the entity the finding is about — the query, the page, the channel — so the same underlying situation keeps the same identity across runs and a dismissal persists.
Three reasons, all about trust. Reproducibility: two people reading the same week must get the same sentence, and a sampled model gives no such guarantee and no regression test. Traceability: every number needs to point back at the row it came from, which a paraphrase destroys. And thin data: a model asked to comment on a table with almost nothing in it will fill the gap with a plausible number, and thin tables are the normal case for a new site.
With one score that all rules compute the same way, not by source and not by severity label. Search Console, analytics, tag manager and social findings all compete for the same attention, so they need a common sort key — here a number from 0 to 100 built from reach, confidence and headroom. Severity stays as the label a reader sees, and is used to break ties so that a critical finding does not sit below a high one at the same score.
The Data API answers questions you can express in its dimensions. The BigQuery export hands over the events themselves, with the costs and caveats that come with owning them.
A cross-network social report fails on two things: metrics that do not mean the same thing, and metrics that were never reported being stored as zero.
