chore: sync skills (agent-skills-v0.86.0, context-mill@v1.13.0) (#66)

Co-authored-by: releaser-ai-plugin[bot] <273148615+releaser-ai-plugin[bot]@users.noreply.github.com>

Author: releaser-ai-plugin[bot]

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "posthog",
   "description": "Access PostHog analytics, feature flags, experiments, error tracking, and insights directly from Claude Code. Optionally capture Claude Code sessions to PostHog LLM Analytics.",
-  "version": "1.1.19",
+  "version": "1.1.20",
   "author": {
     "name": "PostHog",
     "email": "hey@posthog.com",

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "posthog",
-  "version": "1.0.18",
+  "version": "1.0.19",
   "description": "Access PostHog analytics, feature flags, experiments, error tracking, and insights directly from Codex",
   "author": {
     "name": "PostHog",

.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "posthog",
   "displayName": "PostHog",
-  "version": "1.1.15",
+  "version": "1.1.16",
   "description": "Access PostHog analytics, feature flags, experiments, error tracking, and insights directly from Cursor",
   "author": {
     "name": "PostHog",

gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "posthog",
-  "version": "1.0.17",
+  "version": "1.0.18",
   "description": "Access PostHog analytics, feature flags, experiments, error tracking, and insights directly from Gemini CLI",
   "mcpServers": {
     "posthog": {

skills/.sync-manifest

@@ -1,6 +1,7 @@
 analyzing-experiment-session-replays
 auditing-experiments-flags
 auditing-warehouse-data-health
+authoring-log-alerts
 cleaning-up-stale-feature-flags
 configuring-experiment-analytics
 configuring-experiment-rollout
@@ -12,6 +13,7 @@ diagnosing-missing-recordings
 diagnosing-sdk-health
 exploring-apm-traces
 exploring-autocapture-events
+exploring-live-traffic
 exploring-llm-clusters
 exploring-llm-costs
 exploring-llm-evaluations

skills/authoring-log-alerts/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: authoring-log-alerts
+description: >
+  Author useful, low-noise log alerts on services in a PostHog project. Use when the user asks to set up
+  alerts for their logs, suggest alerts they should add, or evaluate whether a service is worth monitoring.
+  Covers service triage, baseline characterisation, threshold drafting, back-testing via simulate, and
+  shipping with a notification destination.
+---
+
+# Authoring log alerts
+
+Authoring an alert is a _measurement_ problem, not a guessing problem. You are not trying to be exhaustive — you
+are trying to land thresholds that fire 0–3 times per week on real production patterns, on services that matter.
+
+## When to use this skill
+
+- The user asks to "set up alerts" / "suggest alerts" for their project.
+- The user wants to evaluate whether a service is producing alertable signal.
+- The user has just enabled log alerting and wants a starter set.
+
+## When _not_ to use this skill
+
+- Tuning an alert that already exists — that's a different job (use `posthog:logs-alerts-events-list` to inspect
+  fire/resolve cadence and `posthog:logs-alerts-partial-update` to adjust).
+- Investigating an active incident — pull rows with `posthog:query-logs`, don't author an alert mid-incident.
+
+## Tools
+
+| Tool                                                                  | Job                                                                           | Where it fits      |
+| --------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ------------------ |
+| `posthog:logs-services`                                               | Top-25 services in window with log_count, error_count, error_rate, sparkline. | Step 1 — triage.   |
+| `posthog:logs-attributes-list` / `posthog:logs-attribute-values-list` | Discover keys/values for narrower filters.                                    | Step 2, optional.  |
+| `posthog:logs-count-ranges`                                           | Adaptive time-bucketed counts for a filter.                                   | Step 3 — baseline. |
+| `posthog:logs-alerts-simulate-create`                                 | Replay a draft config against `-7d` history with full state machine.          | Step 4 — validate. |
+| `posthog:logs-alerts-create`                                          | Persist the alert.                                                            | Step 5 — ship.     |
+| `posthog:logs-alerts-destinations-create`                             | Wire the alert to Slack or webhook.                                           | Step 5 — ship.     |
+
+Do **not** call `posthog:query-logs` during authoring. You need distributions, not rows. Reserve `posthog:query-logs` for
+the very end if the user asks "show me a sample of what would have fired" — `limit: 10` is plenty.
+
+## Workflow
+
+### 1. Triage — pick candidate services
+
+Call `posthog:logs-services` for the last 24h with no filters. The response is capped at 25 services and includes a
+sparkline, so it is small and bounded.
+
+A service is a candidate when **both** are true:
+
+- `log_count` is non-trivial (≥ ~1k in 24h — quieter services produce too little signal to alert on).
+- `error_rate` is non-zero, **or** the user has named the service explicitly.
+
+Skip services with high volume but `error_rate == 0` unless the user wants a volume-shape alert (e.g. "warn me
+if api-gateway suddenly stops producing logs"). Volume-floor alerts use `threshold_operator: below` and need
+different reasoning — see [references/volume-floor-alerts.md](./references/volume-floor-alerts.md).
+
+If the user names a service, treat it as a candidate even without error signal.
+
+### 2. (Optional) Narrow the filter
+
+If a service has many error sub-types, an alert on "all errors" is usually too broad. Use
+`posthog:logs-attributes-list` (try `attribute_type: log`) and `posthog:logs-attribute-values-list` to find a discriminator —
+common ones are `http.status_code`, `error.type`, `k8s.container.name`. Add the narrowing filter to your draft.
+
+Keep it simple: one severity filter + one or two attribute filters is plenty. Multi-clause filters are
+harder to reason about and rarely improve precision.
+
+### 3. Baseline — characterise the candidate over 7 days
+
+Call `posthog:logs-count-ranges` with the candidate's filters, `dateRange: { date_from: "-7d" }`, and
+`targetBuckets: 24` (one bucket ≈ 7h). The response gives you bucket counts.
+
+**Do not eyeball the percentiles or scale the threshold to the alert window manually.** Pipe the
+count-ranges response into the helper script:
+
+```bash
+echo '<count-ranges JSON>' | python3 scripts/baseline_stats.py --window-minutes 5
+```
+
+The script returns:
+
+```json
+{
+  "n_buckets": 12,
+  "bucket_minutes": 420.0,
+  "alert_window_minutes": 5,
+  "stats": { "p50": 12.0, "p95": 71.25, "p99": 126.25, "max": 140 },
+  "suggested_threshold_count": 5,
+  "rationale": "max(p99=126.25, median*3=36.0, floor=5) scaled from 420m bucket to 5m window",
+  "health": []
+}
+```
+
+Use `suggested_threshold_count` as your starting threshold. Read `health`:
+
+| `health` flag           | What it means                                | What to do                                                                                                 |
+| ----------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `sparse:N_of_M_buckets` | Too few non-empty buckets for a 7d baseline. | Widen filter, extend to `-30d`, or skip.                                                                   |
+| `empty`                 | All buckets are zero.                        | Skip — no signal.                                                                                          |
+| `spiky`                 | `max` is 10×+ `p95`.                         | Count-threshold alerts work well. Proceed.                                                                 |
+| `flat`                  | `p95` ≈ `p50`.                               | Be cautious — either no incidents in lookback, or the metric is too smooth. Try a longer lookback or skip. |
+| `[]` (empty)            | Healthy distribution.                        | Proceed.                                                                                                   |
+
+### 4. Draft and simulate
+
+Pick a starter draft from these defaults — see [references/threshold-defaults.md](./references/threshold-defaults.md)
+for the reasoning:
+
+| Setting               | Default                                     | Notes                                                                 |
+| --------------------- | ------------------------------------------- | --------------------------------------------------------------------- |
+| `threshold_count`     | `suggested_threshold_count` from the script | Already scaled to the alert window.                                   |
+| `threshold_operator`  | `above`                                     | Use `below` only for volume-floor alerts.                             |
+| `window_minutes`      | `5`                                         | Allowed: 5, 10, 15, 30, 60. Must match what you passed to the script. |
+| `evaluation_periods`  | `3`                                         | M in N-of-M.                                                          |
+| `datapoints_to_alarm` | `2`                                         | N in N-of-M. 2-of-3 reduces flap from a single noisy bucket.          |
+| `cooldown_minutes`    | `30`                                        | Minimum time between repeat fires.                                    |
+
+Call `posthog:logs-alerts-simulate-create` with these settings and `date_from: "-7d"`. The response gives you `fire_count`
+and `resolve_count`.
+
+### 5. Iterate — three rounds, then ship or skip
+
+Target: `fire_count` between 0 and ~3 over `-7d`. If outside the band:
+
+| Outcome                                                         | Adjustment                                                                                           |
+| --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `fire_count` = 0 over 7d _and_ the baseline was spiky           | Lower `threshold_count` toward `stats.p95` from the script, or drop to 1-of-2.                       |
+| `fire_count` = 0 _and_ the baseline was flat                    | The service has no alertable signal. Skip it; log why.                                               |
+| `fire_count` > 5                                                | Raise `threshold_count` toward `stats.max` from the script, or move to 3-of-5 for a smoother window. |
+| `fire_count` is fine but resolve_count never matches fire_count | Cooldown is too long, or the underlying state is genuinely sticky. Acceptable for now.               |
+
+When adjusting the threshold, **read values from the script's `stats` block — never recompute percentiles
+by hand.**
+
+Cap iteration at **3 simulate calls per candidate**. If you can't land in the band in 3 rounds, the metric
+is wrong — either the filter is too broad, the window is wrong, or the service genuinely doesn't have a
+threshold-shape signal. Note it and move on.
+
+### 6. Ship — create + attach destination
+
+Once a draft simulates cleanly:
+
+1. Call `posthog:logs-alerts-create` with the validated config. Use a name like `<service> error rate (auto)` so the
+   user can see at a glance which alerts came from this skill.
+2. Call `posthog:logs-alerts-destinations-create` to wire it to a notification target. **An alert with no destination
+   is silent.** Always confirm the channel name or webhook URL with the user before attaching — never wire
+   an auto-generated alert to a production channel without explicit confirmation. If the user is unsure,
+   suggest a low-traffic testing channel for the first few alerts.
+
+If the user wants alerts created in `enabled: false` state for review-then-flip, pass `enabled: false` to
+`-create` and tell them how many drafts you produced.
+
+## Filter shape — required
+
+The `filters` field on `posthog:logs-alerts-create` takes a subset of `LogsViewerFilters` and **must contain at
+least one of**:
+
+- `severityLevels` — list of `["trace","debug","info","warn","error","fatal"]`
+- `serviceNames` — list of service name strings
+- `filterGroup` — property filter group
+
+The same shape goes into `posthog:logs-alerts-simulate-create`'s `filters` field. Match the simulate filters to the alert filters
+exactly — otherwise the simulation is testing a different alert than the one you ship.
+
+Example minimum:
+
+```json
+{
+  "severityLevels": ["error", "fatal"],
+  "serviceNames": ["api-gateway"]
+}
+```
+
+## Token-economy rules
+
+- One `posthog:logs-services` call at the start, not per-candidate.
+- One `posthog:logs-count-ranges` call per candidate at `targetBuckets: 24`. Don't go above 30 during authoring.
+- ≤ 3 `posthog:logs-alerts-simulate-create` calls per candidate.
+- Zero `posthog:query-logs` calls during the authoring loop.
+- Prefer reporting a small set of well-validated alerts over a long list of unvalidated drafts.
+
+## Output
+
+Report what you did, in this shape:
+
+- For each shipped alert: name, filters, threshold, simulated fire_count over 7d, destination.
+- For each skipped candidate: service name + why (flat baseline, can't land threshold, low volume).
+- Total simulate calls made, total alerts created.
+
+The user should be able to read this and decide whether to disable any drafts before they go live.

skills/authoring-log-alerts/references/threshold-defaults.md

@@ -0,0 +1,65 @@
+# Threshold defaults — reasoning
+
+The math here is implemented in [`../scripts/baseline_stats.py`](../scripts/baseline_stats.py). The agent
+should not reproduce these calculations inline — pipe the `posthog:logs-count-ranges` response into the script and
+read `suggested_threshold_count`. This section explains _what the script computes and why_, so you can
+sanity-check its output and reason about edge cases.
+
+## `threshold_count = max(p99, median × 3, floor) × (window_minutes / bucket_minutes)`
+
+The bucket-level threshold takes the max of three terms:
+
+1. **p99 of bucket counts.** The 99th percentile of recent buckets is a data-driven "above normal" line.
+   Works when the baseline has enough non-empty buckets to compute a percentile.
+2. **median × 3.** Catches services where p99 is misleadingly close to the median (flat baselines), or where
+   the lookback didn't include any spikes.
+3. **floor (default 5).** Alerting on counts of 1 or 2 produces too much noise on small services. Below 5
+   matches/window, prefer a different alert shape (e.g. existence-based) or skip.
+
+The bucket-level threshold is then **rate-scaled to the alert window** — a 7h bucket with a threshold of
+1000 errors equals ~12 errors per 5-minute window. The script does this scaling; the rationale field shows
+the math.
+
+The scaling assumes errors arrive uniformly within a bucket, which is rarely true — a real spike can pack
+the entire bucket's count into a single 5-minute window. That's exactly why `posthog:logs-alerts-simulate-create` is the
+final arbiter: it replays the alert state machine against actual per-minute history, not the rate-scaled
+average.
+
+## `window_minutes = 5`
+
+The default minimum. Reasons to go higher:
+
+- The service is bursty in 5-minute chunks but the _trend_ over 30 minutes is what matters → use 30.
+- Notifications at 5-minute resolution would be too noisy for the user (e.g. expected periodic spikes during
+  cron) → smooth with a 30 or 60 minute window.
+
+Allowed: `5`, `10`, `15`, `30`, `60`. Don't pick a value not on this list — the API rejects it.
+
+## `evaluation_periods = 3`, `datapoints_to_alarm = 2` (2-of-3)
+
+N-of-M is the cheap, high-signal way to dampen flap. 2-of-3 means: out of the last 3 check intervals, at
+least 2 must breach to fire. A single noisy interval doesn't trip the alert. A sustained problem still does.
+
+When to deviate:
+
+- **1-of-1** — fire instantly on a single bucket breach. Use only for incidents you cannot afford to delay
+  (e.g. payments service erroring at all).
+- **3-of-5** — smoother, slower. Use when the service has known short bursts that are not real incidents.
+- Higher than 5 — diminishing returns; if 5 buckets aren't enough signal, the threshold is wrong.
+
+## `cooldown_minutes = 30`
+
+After a fire, suppress repeat fires for 30 minutes. This avoids paging the same channel every check interval
+during an ongoing incident — once the alert is firing, the user already knows.
+
+Use 0 for snapshot-style alerts where every breach is independently interesting (rare).
+
+## Avoid these footguns
+
+- **`threshold_operator: below` without justification.** Below-threshold alerts measure absence — useful for
+  "service stopped logging" but easy to misuse. If the service has any quiet hours (overnight, weekends),
+  a below-threshold alert will fire at 3am every night. See [volume-floor-alerts.md](./volume-floor-alerts.md).
+- **Filtering by message text alone (`searchTerm` or `message icontains`).** Brittle to log format changes.
+  Prefer a structured attribute (`http.status_code`, `error.type`) when one exists.
+- **Filtering by `trace_id`/`span_id`.** Not useful in alerts — these are per-request and never repeat at a
+  rate that crosses a meaningful threshold.

skills/authoring-log-alerts/references/volume-floor-alerts.md

@@ -0,0 +1,46 @@
+# Volume-floor alerts (`threshold_operator: below`)
+
+Use to alert when a service _stops_ producing logs — a strong signal that the service is down, the logging
+pipeline is broken, or something upstream stopped sending traffic.
+
+## When to use
+
+- The user says "tell me if X stops logging."
+- A service has dependably constant volume across all hours (no nightly drop, no weekend drop) and the user
+  cares about availability.
+
+## When NOT to use
+
+- The service has any quiet hours (overnight, weekends, batch-only). Below-threshold alerts will fire every
+  quiet period.
+- The service is bursty by design — a 5-minute "no logs" window is normal.
+- You don't have at least 7 days of stable baseline. With less data, "below normal" is unknowable.
+
+## How to size the threshold
+
+The `baseline_stats.py` script doesn't suggest below-thresholds directly — derive it manually from the
+script's output. Don't compute by hand; use Python:
+
+```bash
+python3 -c "import sys, json; d=json.load(sys.stdin); print(max(1, round(d['stats']['p50'] * (5/d['bucket_minutes']) * 0.25)))" < stats.json
+```
+
+The reasoning:
+
+1. Take `p50` from the script (the typical bucket count).
+2. Rate-scale to the alert window (`window_minutes / bucket_minutes`).
+3. Multiply by 0.25 — fire when volume drops to 25% of the typical bucket. Buffer absorbs normal variance.
+4. Set `threshold_operator: below`.
+
+## Recommended N-of-M for floors
+
+- `evaluation_periods: 3`, `datapoints_to_alarm: 3` (3-of-3) — require 3 consecutive quiet windows. A single
+  blip won't fire.
+- `window_minutes: 15` minimum — 5-minute floor alerts on noisy services are unreliable.
+- `cooldown_minutes: 60` — once you know the service is quiet, no point re-paging every check.
+
+## Simulate is essential here
+
+Floor alerts are easy to misconfigure into "fires every night." Always run `posthog:logs-alerts-simulate-create` over `-7d`
+before shipping. If `fire_count > 0` and the user has not had outages in the last 7 days, the threshold is
+too aggressive.