/authoring-insight-alerts

name: authoring-insight-alerts
description: >
  Author insight alerts that notify when a trends, SQL, or funnel insight crosses a bound, changes sharply,
  or looks anomalous. Use when the user asks to alert on a metric or insight, get notified when a number
  drops or spikes, set up anomaly detection, or use the AI anomaly detector (the llm detector type).
  Covers choosing between threshold, relative change, statistical detector, and AI detector, previewing
  with alert-simulate before saving, the AI detector's credit cost and limits, the exact create payload,
  and delivery by email or Slack.

Authoring insight alerts

An insight alert checks one saved insight on a schedule and notifies people when the latest value breaks a rule. The job is to pick the rule that matches what the user means by "something is wrong", preview it against real history, and ship it with a cadence and a destination the user agreed to.

When to use this skill

• The user asks to alert on a saved insight, a metric, or a SQL query result.
• The user wants anomaly detection on a metric, or asks for the AI detector.
• The user asks which kind of alert fits a metric.

When not to use this skill

• Alerts on log lines: use `authoring-log-alerts`.
• Alerts on exceptions or error tracking issues: use `authoring-error-tracking-alerts`.
• Explaining why an existing alert fired: read its checks with `posthog:alert-get`, then investigate the metric.

Tools

| Tool | Job | | ---------------------------------------- | --------------------------------------------------------------- | | `posthog:insight-get` | Read the insight's query kind, interval, series, and breakdown. | | `posthog:alerts-list` | Find alerts that already watch the insight (`insight_id`). | | `posthog:alert-simulate` | Preview a detector on the insight's history without saving. | | `posthog:alert-create` | Save the alert. | | `posthog:alert-update` | Change, disable, or snooze an alert. | | `posthog:alert-get` | Read an alert's config and recent checks. | | `posthog:integrations-channels-retrieve` | List connected Slack workspaces and channels. | | `posthog:alert-destinations-create` | Post the alert to a Slack channel as well as email. | | `posthog:user-get` | Look up a user ID for `subscribed_users`. |

Workflow

1. Read the insight and the alerts already on it

Call `posthog:insight-get` and note:

• The query kind: `TrendsQuery`, `HogQLQuery` (SQL), or `FunnelsQuery`. It decides the `config` type.
• The interval (hour, day, week) and how many series or formula results it returns.
• Whether it has a breakdown, and for trends whether it is a time series (a line or bar chart over time, not a single number or a pie).

Call `posthog:alerts-list` with `insight_id`. If an alert already watches the same series, offer to change it with `posthog:alert-update` instead of adding a second one. Each plan limits the number of alerts, so a duplicate can block an alert the user needs later.

If no saved insight measures what the user wants, create the insight first, then come back here.

2. Pick the alert type

Ask what "wrong" means for this metric, then map the answer:

| The user says | Alert type | Shape | | -------------------------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------ | | "Tell me if it goes above 500" or "below 10" | Threshold | `condition: absolute_value`, absolute `lower` or `upper` bound. | | "Tell me if it drops 20% from the previous period" | Relative change | `condition: relative_decrease` or `relative_increase`, percentage bound. | | "Tell me if it looks unusual" on a noisy or seasonal metric | Statistical detector | `detector_config` with `zscore`, `mad`, or `iqr`, or an `ensemble`. | | What counts as unusual is easier to describe in words than a number | AI detector | `detector_config: {"type": "llm", "instructions": "..."}`. | | "Tell me if it stops", for example no signups or a missing heartbeat | Threshold with a lower bound | `absolute_value` with `lower: 1`. |

Prefer the simplest type that matches. A fixed bound is easy to read in a notification and costs nothing to run. Use a detector when the user cannot name a number, or when the metric's normal level moves too much for a fixed bound.

Detectors work on trends and SQL insights, not funnels. On a trends insight they need a time series. See [references/payloads.md](./references/payloads.md) for the exact payload for each type and insight kind.

3. Pick the cadence

`calculation_interval` is one of `hourly`, `daily`, `weekly`, `monthly`, `every_15_minutes`, or `real_time`. If the user did not say how often to check, ask. When they want "as fast as possible", propose `hourly`.

• `every_15_minutes` needs a Boost, Scale, or Enterprise add-on, and `real_time` needs a Scale or Enterprise plan.

A create refused on `calculation_interval` means the plan does not include that cadence. Tell the user and offer `hourly`. Do not try other fast cadences on your own.

• A cadence faster than the insight's interval checks the same completed bucket until the next one closes.

For an hourly check of a daily insight, set `check_ongoing_interval: true` with an upper bound so