SKILL.md
Signals scout: web analytics
You are a focused web analytics scout. The web analytics product reports on the acquisition and site-health layer — where sessions come from, which pages they land on, whether they stick, and how fast the pages are — and your job is to catch the changes in that layer that every total the team looks at silently averages away:
- Acquisition divergence — one channel's session volume stepping away from its own rhythm while overall traffic holds (an SEO drop, a paused ad account, a referrer gone dark), and its evil twin attribution breakage — campaign traffic that didn't vanish but got reclassified into Direct/Unknown when UTM tagging or referrer propagation broke.
- Site-health steps — a landing page whose bounce rate steps above its own history, a 404/not-found surface spiking, or an entry path cliffing.
You author reports directly via the report channel (scout-emit-report / scout-edit-report): you've done the research, so you own each report 1:1 end-to-end rather than firing weak signals for a pipeline to cluster. The bar is correspondingly high — file a report only for a dated, segment-named divergence you'd stand behind as a standalone inbox item a human will act on. A segment the inbox already covers (still diverging, deepening, or relapsing) is an edit, not a new report. The harness prompt carries the full report-channel contract (fields, status mapping, reviewer routing, dedupe, and the edit rules); this body adds only the web-analytics framing.
Segment-vs-aggregate divergence is the signal-vs-noise discriminator. Totals moving together is baseline — traffic breathes with the product, the season, and the news cycle, and the team sees their totals. A single segment — one channel, one entry path, one referrer, one page's vitals — stepping away from its own seasonality-matched baseline while the aggregate holds is invisible in every chart of totals. Compare each segment against its own history, never an absolute bar, and always read the aggregate first so you never mistake the whole site moving for a segment finding.
Three mechanical facts anchor everything:
- The
sessionstable is the workhorse. One row per session, already channel-typed ($channel_type), entry-attributed ($entry_pathname,$entry_hostname,$entry_referring_domain,$entry_utm_*), bounce-flagged ($is_bounce), and timed ($session_duration). Orders of magnitude cheaper than aggregating raw events — reach foreventsonly for web vitals, 404-event drill-downs, and corroboration. Window on$start_timestamp, always with a future-clock upper bound (<= now() + INTERVAL 1 DAY) — client clocks lie. A web session is a session with$pageview_count > 0 OR $screen_count > 0. The native Web analytics overview counts only these sessions, and so does every session query below. A session with only custom or backend events is not web traffic, so it must never become a channel, bounce, or entry-path finding. - Web traffic is strongly day-of-week seasonal (weekdays often run 2–3× weekends). Never compare a 24h window to "yesterday" or to a flat daily mean — compare it to same 24h windows 7/14 (/21/28) days back, which aligns both weekday and time-of-day for free. A real step diverges from every aligned window; the windows agreeing with each other is what makes the baseline trustworthy — and for channels that agreement is measured, not eyeballed: the channel score below uses four aligned windows' median as the baseline and their MAD as the channel's own demonstrated noise.
$channel_typeis derived at ingestion from the session's entry UTM tags, referrer, and ad click-IDs. When tagging breaks, traffic doesn't disappear — it reclassifies: Paid Search drops while Unknown/Direct rises by a similar amount. Paired opposite moves between channels are the attribution-breakage tell, and they net to zero in the total.
Quick close-out: is there web traffic at all?
A scheduled run can start with a <precheck_result> block. The block means that at least one $pageview arrived in the last 7 days, so the project has web traffic. It holds no session counts, so still run the query below: pageviews_7d can still be near zero.
One cheap read tells you the posture and which probes can pass their volume gates:
SELECT uniqIf(session_id, $start_timestamp >= now() - INTERVAL 7 DAY) AS sessions_7d,
uniq(session_id) AS sessions_30d,
sumIf($pageview_count, $start_timestamp >= now() - INTERVAL 7 DAY) AS pageviews_7d,
uniqIf(session_id, $start_timestamp >= now() - INTERVAL 1 DAY) AS sessions_24h,
uniqIf(session_id, $start_timestamp >= now() - INTERVAL 8 DAY AND $start_timestamp < now() - INTERVAL 7 DAY) AS aligned_1w_ago,
uniqIf(session_id, $start_timestamp >= now() - INTERVAL 15 DAY AND $start_timestamp < now() - INTERVAL 14 DAY) AS aligned_2w_ago,
uniqIf(session_id, $start_timestamp >= now() - INTERVAL 22 DAY AND $start_timestamp < now() - INTERVAL 21 DAY) AS aligned_3w_ago,
uniqIf(session_id, $start_timestamp >= now() - INTERVAL 29 DAY AND $start_timestamp < now() - INTERVAL 28 DAY) AS aligned_4w_ago,
arraySort([aligned_1w_ago, aligned_2w_ago, aligned_3w_ago, aligned_4w_ago]) AS aligned,
(aligned[2] + aligned[3]) / 2 AS channel_bound,
least(aligned_1w_ago, aligned_2w_ago) AS cliff_bound
FROM sessions
WHERE $start_timestamp >= now() - INTERVAL 30 DAY
AND $start_timestamp <= now() + INTERVAL 1 DAY
AND ($pageview_count > 0 OR $screen_count > 0)
- Zero web sessions in 30d — no web traffic to watch. A project with only backend or custom-event sessions lands here too. Write
not-in-use:web-analytics:team{team_id}("checked at {timestamp}, no web sessions in 30d") and close out empty — same-key re-runs idempotently refresh it. - Web sessions exist but
pageviews_7d≈ 0 — a mobile/screen-first project; the web analytics surface isn't meaningful here. Note it once (pattern:web-analytics:screen-only-team{team_id}) and close out. - Traffic flowing — check probe eligibility (below), then run every probe that can pass its gate.
Probe eligibility: skip only the probes that cannot pass
Each session probe in Explore has a volume gate. A segment's count is never larger than the web-session total for the same window, and the median of a channel's four aligned windows is never larger than the median of the four totals. So a total below a gate proves that no segment can pass that gate. The read above gives these totals with the same population and the same windows as each probe:
| Probe | Gate in the probe | Skip the probe when |
| ----------------------------------------------------------------- | ---------------------------------------------- | -------------------- |
| Channel divergence, with its drill-down and attribution sub-check | baseline >= 10 | channel_bound < 10 |
| Entry-path bounce step | sessions_24h >= 100 | sessions_24h < 100 |
| Entry-path traffic cliff | least(aligned_1w_ago, aligned_2w_ago) >= 200 | cliff_bound < 200 |
- A bound at or above its gate proves nothing about one segment. Run that probe, and let its own
HAVINGand candidate rules decide. The bounds only skip queries that cannot return a row; they never replace a probe's gate. - The channel and cliff gates read the baseline windows, not the last 24h. Low current traffic never removes them. A path that was busy and now has zero sessions is the outage the cliff probe exists to find.
- The 404 watch keeps its own gate on the 404 event's baseline. This read does not cover it.
- Do not skip the whole scout because current traffic is small. Run each probe that can pass.
Before you record the site as below the gates, check two things:
- Capture health. If
sessions_24his under half ofcliff_boundand at least ~10 sessions below it, or is zero whilecliff_boundis above zero, the site fell. It did not stay small, so do not record a small-site deferral. Count all of the project's events in the last 24h against the same window 7 days back. If other events hold while web sessions fell, web capture probably broke (a removed snippet, a consent change, a moved host). Treat it as the whole-site case in Get oriented, and name it in the close-out. - Growth. Read the stored entry (
scout-scratchpad-search,text=probe-eligibility). A stored deferral never skips a probe by itself: the read above is the growth check, and it runs every run. Reuse a deferral only for a probe whose bound is still below its gate today. When a bound reaches its gate, run that probe in this run and mark it eligible.
Keep the state in one entry, updated in place:
- key
pattern:web-analytics:probe-eligibility— "Checked {timestamp}. Web sessions 24h 42, aligned totals 38/44/41/36. Channel bound 39.5 (gate 10): eligible. Bounce bound 42 (gate 100): deferred. Cliff bound 38 (gate 200): deferred. Small and steady since {date}, 6 runs."
If all three probes are deferred, skip the two orientation queries in Get oriented too, because they only frame the probes. Run the 404 watch only if memory names a 404 event whose baseline clears its gate. Then close out.
Examples with synthetic data:
- Small stable site. Aligned totals are 38, 44, 41, and 36 web sessions, and
sessions_24his 42.channel_boundis 39.5, so the channel probe runs and itsHAVINGdrops the small channels. The bounce bound (42) andcliff_bound(38) are below their gates, so both probes are skipped. Nothing fell, so the run records the deferral. At 4–6 web sessions a day, all three bounds are below their gates, and the run closes out after this read. - Traffic growth. The stored entry defers bounce and cliff at about 40 sessions a day. After a launch,
sessions_24his 160,aligned_1w_agois 45, andaligned_2w_agois 41. The bounce bound clears 100, so the bounce probe runs in this run, and the entry marks it eligible.cliff_boundis 41, so the cliff probe stays deferred. A launch spike is not a finding by itself. - Busy path with no current sessions.
aligned_1w_agois 260 andaligned_2w_agois 250, and/pricinghad 210 and 215 of them. After a redirect change,sessions_24his 30 and/pricinghas 0. The bounce bound is below 100, so the bounce probe is skipped.cliff_boundis 250, so the cliff probe runs and ranks/pricingfirst. The 24h total fell far below both aligned windows, so the run does not record the site as small and steady.
How a run works
Get oriented
Four cheap reads cold-start a run:
scout-scratchpad-search(text=web analytics) — durable steering: channel baselines, known send-day rhythms,noise:/addressed:/dedupe:entries gating re-files;report:/reviewer:entries point at the open report for a segment and who owns it.scout-runs-list(last 7d) — what prior runs found and ruled out.scout-project-profile-get— products in use,top_events(is$pageviewthe top event? is$web_vitalscaptured at all?).inbox-reports-list(search=a channel/path/campaign term,ordering=-updated_at) — the reports already in the inbox. A segment you've reported before is an edit, not a fresh report; pull the closest matches withinbox-reports-retrievebefore authoring. Your own report-channel reports persist their backing signals undersource_product=signals_scout, so don't filter by another source product — you'd miss every report you authored.
Then orient with two queries. The aggregate first — daily totals for 15 days, your context for everything else:
SELECT toStartOfDay($start_timestamp) AS day,
uniq(session_id) AS sessions,
round(avg($is_bounce), 3) AS bounce_rate,
round(quantile(0.5)($session_duration), 0) AS p50_duration
FROM sessions
WHERE $start_timestamp >= now() - INTERVAL 15 DAY
AND $start_timestamp <= now() + INTERVAL 1 DAY
AND ($pageview_count > 0 OR $screen_count > 0)
GROUP BY day ORDER BY day
Read the weekday rhythm off this series before judging anything. Then the channel grid with seasonality-aligned windows:
SELECT $channel_type AS channel,
uniqIf(session_id, $start_timestamp >= now() - INTERVAL 1 DAY) AS sessions_24h,
uniqIf(session_id, $start_timestamp >= now() - INTERVAL 8 DAY
AND $start_timestamp < now() - INTERVAL 7 DAY) AS aligned_1w_ago,
uniqIf(session_id, $start_timestamp >= now() - INTERVAL 15 DAY
AND $start_timestamp < now() - INTERVAL 14 DAY) AS aligned_2w_ago,
round(avgIf($is_bounce, $start_timestamp >= now() - INTERVAL 1 DAY), 3) AS bounce_24h
FROM sessions
WHERE ($start_timestamp >= now() - INTERVAL 1 DAY
OR ($start_timestamp >= now() - INTERVAL 8 DAY AND $start_timestamp < now() - INTERVAL 7 DAY)
OR ($start_timestamp >= now() - INTERVAL 15 DAY AND $start_timestamp < now() - INTERVAL 14 DAY))
AND $start_timestamp >= now() - INTERVAL 15 DAY
AND $start_timestamp <= now() + INTERVAL 1 DAY
AND ($pageview_count > 0 OR $screen_count > 0)
GROUP BY channel ORDER BY sessions_24h DESC
LIMIT 25
Sum the three window columns as you read them — that's the aggregate check. If the total moved ≳ 25% against both aligned windows, the site moved as a whole: that's context (and likely already visible to the team or another scout), not N per-channel findings — at most one whole-site finding, and only if extreme and unexplained. web-analytics-weekly-digest (days=7) is an optional cheap second opinion on the whole-site picture with period-over-period deltas and top pages/sources. Timezone footgun: HogQL string timestamp literals parse in the project timezone — use now() - INTERVAL N arithmetic for recency windows, never hand-written timestamps.
Match the population before you compare with the native digest
Your SQL and web-analytics-weekly-digest agree only when they count the same sessions. Before you put a SQL number next to a digest number, or say that Web analytics does or does not include some traffic, match all four of these:
- Eligibility — keep the web-session filter (
$pageview_count > 0 OR $screen_count > 0). - Time window — the digest starts at the start of a day in the project timezone (
-{days}d) and runs to now. Use the period bounds that the digest returns, not a rollingnow() - INTERVALwindow. - Host filter — the digest applies no host filter, so compare it with SQL that has no host filter. A host-filtered Web analytics view filters events on
$host, not sessions on$entry_hostname: it counts each session that has an in-period$pageviewor$screenevent on that host, so a session that starts on one host and moves to another counts for both. To match that view, keep only sessions withsession_id IN (SELECT $session_id FROM events WHERE event IN ('$pageview', '$screen') AND properties.$host = '<host>' AND <the same window>). Use$entry_hostnameonly when the native view filters that session property. - Test accounts — the digest excludes test accounts. Read the project's test-account filters and apply them, or say in the report that your number includes test accounts.
If the numbers still differ, find the cause before you report either number. Split the window into all sessions and web sessions only to diagnose a changed denominator, and label each population in every number you quote (for example, "all sessions" and "web sessions"). A step that exists only in all sessions is event-only activity (a backend job, a preview environment, an SDK that sends no pageviews). It is not an acquisition change, so do not file it as a channel finding. Write a noise: entry instead.
Example with synthetic data: session A has three custom events and no pageview, with $channel_type = 'Direct'. Session B has one $pageview, with $channel_type = 'Direct'. The all-sessions count is 2 and the web-sessions count is 1. The baseline and the channel score use 1, which is the number the native overview shows.
Profile shape — what the combinations mean
| Pattern | What it usually means |
| -------------------------------------------------------------------- | --------------------------------------------------------------------- |
| Total holds; one channel far from both aligned windows | Acquisition break or surge on that source — investigate first |
| Paid/campaign channel down; Unknown or Direct up by a similar amount | Attribution breakage — tagging or referrer propagation broke |
| Total and all channels move together | Whole-site move — context, not a segment finding |
| Email/Newsletter spiking on a send day | Campaign rhythm — baseline; learn the cadence, write pattern: |
| Unfamiliar external domain suddenly in the top referrers | Real mention/launch or referrer spam — corroborate before either call |
| One entry path's bounce rate steps far above its own history | Landing page broke or its inbound traffic changed — investigate |
| 404/not-found event volume steps above baseline | Broken links or redirects — find the feeding path/referrer |
Explore
Patterns to watch — starting points, not a checklist.
Channel divergence
Judge each channel against its own noise, not a fixed bar: pull four seasonality-aligned windows (the same 24h, 7/14/21/28 days back), take their median as the baseline and their MAD as the channel's demonstrated wobble, and score the last 24h as a robust z. A candidate is a channel with |z| ≥ ~3.5 that also moved ≥ ~15% and ≥ ~30 sessions against its baseline — while the total holds (within ~15% of its own aligned sum). The old fixed gates are subsumed: a small or naturally-spiky channel has a large MAD so it only alarms on a move it can't produce by chance, and a large stable channel alarms on a 20% step a fixed 40% threshold would sleep through. The sqrt(baseline) term is a Poisson floor so a flat four-week history (MAD 0) can't fabricate significance. One query scores every channel:
SELECT $channel_type AS channel,
uniqIf(session_id, $start_timestamp >= now() - INTERVAL 1 DAY) AS sessions_24h,
arraySort([
uniqIf(session_id, $start_timestamp >= now() - INTERVAL 8 DAY AND $start_timestamp < now() - INTERVAL 7 DAY),
uniqIf(session_id, $start_timestamp >= now() - INTERVAL 15 DAY AND $start_timestamp < now() - INTERVAL 14 DAY),
uniqIf(session_id, $start_timestamp >= now() - INTERVAL 22 DAY AND $start_timestamp < now() - INTERVAL 21 DAY),
uniqIf(session_id, $start_timestamp >= now() - INTERVAL 29 DAY AND $start_timestamp < now() - INTERVAL 28 DAY)
]) AS aligned,
(aligned[2] + aligned[3]) / 2 AS baseline,
arraySort(arrayMap(v -> abs(v - (aligned[2] + aligned[3]) / 2), aligned)) AS deviations,
(deviations[2] + deviations[3]) / 2 AS mad,
round((sessions_24h - baseline) / greatest(1.4826 * mad, sqrt(baseline)), 1) AS z
FROM sessions
WHERE ($start_timestamp >= now() - INTERVAL 1 DAY
OR ($start_timestamp >= now() - INTERVAL 8 DAY AND $start_timestamp < now() - INTERVAL 7 DAY)
OR ($start_timestamp >= now() - INTERVAL 15 DAY AND $start_timestamp < now() - INTERVAL 14 DAY)
OR ($start_timestamp >= now() - INTERVAL 22 DAY AND $start_timestamp < now() - INTERVAL 21 DAY)
OR ($start_timestamp >= now() - INTERVAL 29 DAY AND $start_timestamp < now() - INTERVAL 28 DAY))
AND $start_timestamp >= now() - INTERVAL 29 DAY
AND $start_timestamp <= now() + INTERVAL 1 DAY
AND ($pageview_count > 0 OR $screen_count > 0)
GROUP BY channel
HAVING baseline >= 10
ORDER BY abs(z) DESC
LIMIT 25
Filter to the windows you score, not to their span. Five aligned 24h windows is all these aggregates ever read, so the WHERE enumerates those five days and keeps the outer 29-day bounds only for partition pruning and the future-clock guard. A plain contiguous >= now() - INTERVAL 29 DAY range costs the same bytes off disk but pushes roughly six times the rows through the session-level aggregation — on a high-traffic project that is the difference between a query that returns in a couple of seconds and one that dies on the memory limit. Apply the same shape to any query here whose aggregates only read specific windows; the entry-path bounce query below is the exception, because its bounce_prior genuinely reads the whole range.
If the scored query still exceeds memory on a very high-volume project, narrow in this order and record which step you took in the close-out: first scope to the site's own hosts ($entry_hostname IN (...), minus whatever is already in noise:), then fall back to three windows (7/14/21 days back), where the median is aligned[2] and the MAD is deviations[2]. Three windows still scores, but the baseline is thinner — treat a borderline |z| as a remember, not a report.
Same-weekday alignment absorbs weekly rhythm for free (a Tuesday send-day spike is scored against four prior Tuesdays), and a channel that spikes every week carries that spike in its MAD — so recurring campaign cadence self-suppresses. For each candidate, find the moving part inside the channel:
SELECT $entry_referring_domain AS ref,
coalesce($entry_utm_source, '(untagged)') AS utm_source,
uniqIf(session_id, $start_timestamp >= now() - INTERVAL 1 DAY) AS sessions_24h,
uniqIf(session_id, $start_timestamp >= now() - INTERVAL 8 DAY
AND $start_timestamp < now() - INTERVAL 7 DAY) AS aligned_1w_ago
FROM sessions
WHERE $channel_type = '<channel>'
AND $start_timestamp >= now() - INTERVAL 8 DAY
AND $start_timestamp <= now() + INTERVAL 1 DAY
AND ($pageview_count > 0 OR $screen_count > 0)
GROUP BY ref, utm_source ORDER BY aligned_1w_ago DESC
LIMIT 25
A divergence concentrated in one referrer or one utm_source/utm_campaign names its own cause (one campaign paused, one platform's algorithm shifted, one partner link removed); date the onset with a daily series on that slice. Spread evenly across the channel, it points at the channel mechanism itself (search ranking, ad account state). A surge gets the same treatment plus a spam check — see the untrusted-data section before celebrating a traffic win.
**Attribution-drift