/authoring-error-tracking-alerts

name: authoring-error-tracking-alerts
description: >
  Author error tracking alerts that fire when an issue is created, reopened, or starts spiking. Use when
  the user asks to set up error notifications, route exceptions to Slack/webhook/Linear, or evaluate which
  error events are worth alerting on. Covers trigger-event selection, integration choice, dedup against
  existing alerts, and shipping with the canonical message body shape.

Authoring error tracking alerts

Authoring an error tracking alert is a _routing_ problem, not a measurement problem. The trigger events already exist and fire on real conditions in the ingestion pipeline — your job is to pick the right trigger for the user's intent, dedupe against what's already configured, and wire a destination they can actually act on.

When to use this skill

• The user asks to set up alerts / notifications for errors or exceptions in their project.
• The user wants a starter set of alerts after enabling error tracking.
• The user pastes an issue link and asks "notify me when this happens again" — usually `_reopened` with a

per-issue property filter.

When _not_ to use this skill

• Tuning the spike detector itself (multiplier, window, threshold). That lives behind the spike detection

config endpoint and is not exposed via MCP today.

• Investigating an active incident — query the issue / its events directly via

`posthog:query-error-tracking-issue` and `posthog:query-error-tracking-issue-events` instead of authoring more alerts mid-fire.

• Configuring volume-threshold alerts (count of `$exception` events over a window). That's a logs-style

alert and is not in scope here — error tracking alerts ride the lifecycle events instead.

Tools

| Tool | Job | Where it fits | | ---------------------------------------------- | ---------------------------------------------------------------- | ---------------------------- | | `posthog:error-tracking-alerts-list` | List existing alerts; dedupe before creating. | Step 2 — dedupe. | | `posthog:integrations-list` | Find the user's Slack workspace id (filter by `kind=slack`). | Step 3 — pick channel. | | `posthog:integrations-channels-retrieve` | List Slack channels for a workspace. | Step 3 — pick channel. | | `posthog:error-tracking-alerts-create` | Create the alert (HogFunction with `type=internal_destination`). | Step 4 — ship. | | `posthog:error-tracking-alerts-partial-update` | Toggle, rename, or modify an existing alert. | When tuning, not authoring. | | `posthog:error-tracking-alerts-delete` | Soft-delete an alert. | When the user says "remove". |

Trigger events — pick exactly one per alert

There are three lifecycle events. Each has a different "noise vs urgency" trade-off — picking the wrong one is the most common cause of alert fatigue here.

| Event | Fires when | Use when | | -------------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `$error_tracking_issue_created` | A brand-new issue first appears. | Small projects, or projects where every new error type is genuinely worth a look. Floods large/noisy projects. | | `$error_tracking_issue_reopened` | A previously resolved issue starts emitting again. | Catch regressions on issues someone already triaged. The safest "I want to know if this comes back" trigger. | | `$error_tracking_issue_spiking` | The spike detector flags abnormal volume on an issue. | Production projects with high baseline volume. Threshold/multiplier is shared across the project — check spike config before using. |

If the user is vague ("alert me on errors"), default to `_spiking`. It's the most signal-dense trigger and the least likely to cause alert fatigue. Confirm explicitly before proceeding.

Workflow

1. Confirm intent

You need three things from the user before creating anything:

• **Which trigger event.** If unspecified, recommend `_spiking` and ask for confirmation. Do not silently

pick one.

• **Which channel.** Slack channel name, webhook URL, Linear team, etc. Never hardcode a production

channel. If the user says "the dev channel", ask for the exact channel id or name.

• **Which scope.** All issues (most common), or scoped to a specific issue / exception type / assignee.

2. Dedupe against existing alerts

Call `posthog:error-tracking-alerts-list`. Filter the response client-side by `filters.events[].id`.

• If an alert exists for the **same event** delivering to the **same channel**, stop. Tell the user it

already exists and ask whether they want to change anything (in which case use `error-tracking-alerts-partial-update`) or skip.

• Multiple alerts on the same event for the same channel produce duplicate Slack messages — the user

almost never wants this.

• Multiple alerts on the same event for **different** channels (e.g. one for `#oncall`, one for the

oncall webhook) is fine and sometimes intentional. Confirm.

PostHog's "alerts configured" recommendation only inspects `filters.events` — adding per-issue `filters.properties` does not affect the status the recommendations card reports.

3. Pick the integration

For Slack:

1. `posthog:integrations-list` with `kind=slack` → pick the integration `id` (an integer). 2. `posthog:integrations-channels-retrieve` with