signoz-explaining-alerts

What this skill does

# Alert Explain

Decode an existing SigNoz alert's configuration into a plain-language
explanation. The skill is read-only and stays focused on the rule
itself: what it watches, when it fires, where it notifies. A single
line of fire-frequency data is included to ground the explanation, but
this skill does **not** investigate any specific fire — that is
`signoz-investigating-alerts`'s job.

## Prerequisites

This skill calls SigNoz MCP server tools (`signoz:signoz_get_alert`,
`signoz:signoz_list_alert_rules`, `signoz:signoz_get_alert_history`). Before running
the workflow, confirm the `signoz:signoz_*` tools are available. If they are
not, run `signoz-mcp-setup` first to initialize or repair the MCP connection.
Do not guess at alert configuration from the rule name alone.

## When to use

Use this skill when the user wants to:
- Understand or interpret an existing alert rule.
- Confirm what signal an alert watches and at what threshold.
- Audit whether an alert is reasonably configured.
- Translate raw alert JSON into operational language.

Do NOT use when the user wants to:
- Create a new alert → `signoz-creating-alerts`.
- Diagnose why an alert fired or correlate signals around a fire window
  → `signoz-investigating-alerts`.
- Modify an existing alert → call `signoz:signoz_update_alert` directly.

## Required inputs

| Input | Required | Source if missing |
|---|---|---|
| Alert identifier (rule ID or name) | yes | `$ARGUMENTS`, recent context, or fuzzy match |

If the input is missing or ambiguous, this skill is **best-effort** (not
strict — read-only operations are cheap to recover from):

1. Call `signoz:signoz_list_alert_rules`, paginate through every page, and find
   the closest name match.
2. State the interpretation in the response:
   "Interpreting your request as alert 'High Error Rate — Checkout' (id 42).
   If you meant a different one, tell me the name or id."
3. Proceed with the explanation. The user can correct after.

## Workflow

### Step 1: Resolve the alert

If the user provided a numeric id, skip to Step 2. Otherwise:

1. Call `signoz:signoz_list_alert_rules` and **paginate every page** —
   `pagination.hasMore` is true until the full list is walked.
2. Match by name (case-insensitive substring). If multiple match,
   present the candidates and ask which one (interactive) or pick the
   closest and flag the assumption (autonomous).

### Step 2: Fetch the full configuration

Call `signoz:signoz_get_alert` with the rule id. This is **mandatory** — the
list response does not include the full condition / thresholds /
notification settings, and explanations based on the name alone are
guesses.

### Step 3: Pull a one-line fire-frequency summary

Call `signoz:signoz_get_alert_history` for the rule with a 7-day lookback. From
the response, derive a single line:

> Fired N times in the last 7d (last fire: <relative-time>).

If the alert never fired in the window, say so explicitly:
"Has not fired in the last 7d." If the alert is disabled, mention that
and skip the history line.

This single line grounds the explanation. Do **not** drill into specific
fires here — that's `signoz-investigating-alerts`.

### Step 4: Build the explanation

The single most useful thing for the user is a tight summary. Lead
with a **TL;DR that directly answers the question they asked**, not a
generic alert summary. The TL;DR is the only thing some users will
read — burying their answer under a fixed template forces them to
scroll for what they wanted in the first place.

Match the TL;DR shape to the user's question:

- **"What does this alert do?" / "Explain X"** — describe what fires:
  > **TL;DR**: Fires when `<condition>` for `<scope>`, notifies
  > `<channel>`. `<fire-frequency line>`.

- **"Is it configured correctly?" / "Audit this" / "Anything I should
  change?"** — lead with the **verdict and the top 1–3 changes**, not
  the description of what fires:
  > **TL;DR**: Mostly well-configured, but recommend: (1) add
  > `alertOnAbsent` — currently a crashed service stays silent; (2)
  > fix annotation template `{{$topic}}` → `{{$labels.topic}}` (won't
  > interpolate); (3) split critical to PagerDuty (both tiers
  > currently route to Slack). `<fire-frequency line>`.

- **"How does X work?" / "Explain the count guard"** — answer the
  mechanism in 1–2 sentences before any framing:
  > **TL;DR**: The count guard is a `having: count() > 50` clause on
  > query A — any 1-minute bucket with ≤50 spans is dropped before
  > evaluation, so low-traffic minutes can't fire the alert.

- **"What's the threshold?" / focused config question** — state the
  exact thing they asked about:
  > **TL;DR**: Threshold is **3 standard deviations** (z-score), not
  > a raw rate value. Daily seasonality means the model compares
  > each hour against historical norms for that hour.

Always include the fire-frequency line and `disabled` status if
non-default — those ground every kind of TL;DR. But put the answer to
the user's specific question first.

After the TL;DR, write the explanation in prose, organized into the
four sections below. **Skip any section that has nothing meaningful to
add** — empty severity labels, default notification settings, vanilla
annotations don't deserve a header. Short and skimmable beats
perfunctorily complete; the user is not reading a checklist.

**1. What it watches** — one short paragraph. Combine signal type
(metrics / logs / traces / exceptions), what the query measures, and
scope. Translate the query to operational language; for formulas, name
each sub-query (A, B, …) and state what F1 (or whichever
`selectedQueryName` triggers) computes — e.g. "F1 = A × 100 / B → error
percentage". Decode filter operators (`=` equals, `!=` not equals,
`IN` / `NOT IN`, `LIKE` / `ILIKE`, `CONTAINS`, `REGEXP`, `EXISTS` /
`NOT EXISTS`); enumerate `IN` / `NOT IN` value lists so the user can
verify them. Name each `groupBy` dimension and its practical effect
("fires separately per service" for `service.name`).

For **anomaly rules** (`ruleType: anomaly_rule`), explicitly state that
the threshold is in **standard deviations from the learned pattern, not
the raw value** — this is the most common point of confusion. Include
`algorithm` (zscore), `seasonality` (hourly / daily / weekly), and how
lower/higher targets shift sensitivity (lower → more noise, higher →
only extreme deviations).

**2. When it fires** — one paragraph covering threshold + timing.
Decode the threshold spec into plain English using these mappings:

- `op` codes: `1` above, `2` below, `3` equal, `4` not equal.
- `matchType` codes: `1` at_least_once (any point in window), `2`
  all_the_times (entire window), `3` on_average (window average), `4`
  in_total (window sum), `5` last (most recent point).

State each threshold tier's `name`, `target`, `targetUnit`, and
attached channels. **Always state the threshold in `targetUnit`, not
the native query unit** (e.g. "fires when p99 exceeds 500 ms", not
"…exceeds 500 000 000 ns"). Note `recoveryTarget` if set (hysteresis);
if absent, mention flap risk when the value hovers near the boundary.
Describe timing as "checks every `<frequency>` over the last
`<evalWindow>`", and mention that with `at_least_once` a single-point
breach triggers, while `all_the_times` requires the full window.

**3. Where it notifies** — channels per tier (resolved by name from
`signoz_list_notification_channels` if needed), `notificationSettings.groupBy`
(how notifications are bundled), `renotify` (interval + which states),
`usePolicy` (label-based routing). Skip this section entirely if
notification settings are vanilla and the user already saw the channel
in the TL;DR.

**4. Notable concerns** — flag *only* what's non-default and worth the
user's attention. Don't list every absent field; focus on the
high-leverage ones:

- **`alertOnAbsent` missing** when the signal is critical: silent data
  loss (crashed service, broken instrumentation) won't trigger the
  alert. Always call