Posthog Errors

Today is ${today}.

${var} — optional scope override. Empty (default) → all projects the OAuth grant covers, last 7 days. Accepts:

• Nd — change the window, e.g. 14d or 30d (bare number also read as days).
• a comma-list of project name substrings — e.g. web, api limits to projects whose name contains one of those (case-insensitive). Combine with a window: web, api, 14d.

This runs unattended — treat ${var} as final, no confirmation step.

Give the operator a single, scannable overview of the errors across every one of their PostHog projects for the past week. The heavy lifting is the PostHog MCP server (mcp.posthog.com/mcp): it enumerates the projects and returns the error-tracking issues, so you reason over structured facts (occurrence counts, users affected, first/last-seen timestamps) instead of guessing. Your job is to fan out across projects, rank by impact, separate new from ongoing, and write the digest.

Capability notes (read before running or editing)

mode: read-only is load-bearing and shapes how this skill writes. The read-only toolset (scripts/skill_mode.sh) drops Write, Edit, and python; it keeps Read, the MCP tools, curl, jq, and Bash for node/cat/echo/mkdir/date/jq. So every file this skill produces — the ./notify body and the state snapshot — is written with a cat heredoc (or node) redirection, never the Write tool and never python. Reaching for python to build or send the digest gets denied mid-run and the notification silently never ships. ./notify itself works in read-only, but its multi-line body must be a file written the way above — and that scratch file goes under /tmp/, never memory//output/ (those are committed; only the Step 4 snapshot and Step 4b report are meant to persist).

Detection & auth

The server is wired in .mcp.json as posthog by the dashboard MCP panel's one-click Connect (OAuth 2.1 + PKCE against oauth.posthog.com; tokens stored as MCP_POSTHOG_TOKEN + MCP_POSTHOG_OAUTH, and a fresh access token minted each run by scripts/mcp-oauth-refresh.sh). Its tools surface as mcp__posthog__* — discover them from the server; the tool descriptions and their parameters are the source of truth, don't assume a fixed list or fixed argument names. The tools you'll reach for are the ones for scope (list organizations, list projects, switch the active organization/project — typically named like organizations-get, projects-get, switch-organization, switch-project) and error tracking (list a project's errors over a date range and fetch one error's detail — typically list-errors / error-details). Use whatever the server actually exposes.

• No mcp__posthog__* tool callable → the server isn't connected (or its OAuth secrets are missing, in which case the workflow logged a ::warning:: and skipped MCP for the whole run). Log POSTHOG_NOT_CONNECTED, notify once pointing the operator at the dashboard → MCP → Connect PostHog, and exit.
• Tools exist but return 401 / "invalid token" / "insufficient scope" → the OAuth access token expired and the refresh failed (typically a rotated refresh token that couldn't be saved back — durable headless refresh needs GH_SECRETS_PAT; see docs/mcp-oauth.md), or the granted scopes are too narrow. Log POSTHOG_AUTH_STALE, notify the operator to re-connect PostHog once in the dashboard, and exit with whatever partial results already came back (clearly marked partial).

"All my projects" is only as wide as the OAuth grant. Connect requests read scopes (user:read, organization:read, project:read, error_tracking:read) across the organizations the operator authorizes — user:read is required just to open the MCP session. If projects are missing from the digest, the grant almost certainly doesn't include them — say so once rather than silently under-reporting.

Steps

1. Enumerate the scope

List the organizations the key can access, then the projects in each (switch the active organization first if the server requires it before listing its projects). Build the working set of {org, project id, project name, region host}. Apply any ${var} name filter here. Region host: prefer whatever the tool returns; otherwise us.posthog.com for US, eu.posthog.com for EU — you need it to build links later.

Call budget: ≤ 60 MCP tool calls per run. These calls are read-only and unmetered (no per-call spend), so the cap is a runtime guard, not a money limit — but respect it. Enumeration is cheap (a handful of calls); the bulk is one list-errors per project below. If the operator has more projects than the budget allows after enumeration, cover projects in listed order, and in the digest name exactly which projects were not reached this run (a silent cap reads as "all clear" when it isn't — see seo-audit's --max discipline).

2. Pull each project's errors

For each project in scope: switch the active project to it, then list its errors for the window — dateFrom = 7 days before ${today} (or the ${var} window), dateTo = ${today}. Order by occurrences and request the top ~15 issues; filter out test accounts if the tool offers it. Capture per issue, verbatim from the tool result — never invent or round a number: the error name/message, occurrence count, users affected, first-seen and last-seen timestamps, and any status (resolved/suppressed) and per-day/sparkline counts the tool returns.

A project that errors or returns nothing: record it (0 errors, or the error) and keep going — one unreachable project must not abort the rest. Only fetch error-details for the top ~5 issues across all projects (for a one-line "what / where" in the digest), and only if the list view didn't already carry it — that keeps you well inside budget.

3. Rank and classify

Across all projects, build one impact-ranked list. Impact = occurrences and users affected (a 50-user error usually outranks a noisy 5-user one at similar volume — say which you're weighting when it's close). Then classify each issue from the data you already have — no stored state required:

• 🆕 New this week — first_seen falls inside the window.
• ⬆️ Spiking — occurrences concentrated in the back half of the window, or a rising per-day trend if the tool returns daily counts. Call it spiking only with evidence; don't infer a trend from a single number.
• Ongoing — first_seen predates the window and volume is roughly flat.
• ✅ Resolved / quiet — marked resolved in PostHog, or last_seen is early in the window with nothing since. Report these too — a digest that only ever delivers bad news gets muted.

4. Cross-week diff (optional, graceful)

Read the most recent prior snapshot if one exists — memory/posthog-errors/*.json, named YYYY-MM-DD.json — and match issues by id (fall back to project+title). Surface two extra signals: issues new since last week's run (not in the prior snapshot), and issues cleared since (in the prior snapshot, absent or zero now). First run, or no prior file → skip this and say "first run — no week-over-week baseline yet" once.

Then write today's compact snapshot before notifying, so next week has a baseline even if the notify step fails. mode: read-only has no Write tool, so use a heredoc redirection (writes to memory/, which the read-only guard preserves) — copy the numeric fields straight from the tool results, don't retype from prose:

mkdir -p memory/posthog-errors
cat > memory/posthog-errors/${today}.json <<'JSON'
{"date":"${today}","window_days":7,"projects":[
  {"id":123,"name":"web-app","issues":[
    {"id":"<issueId>","title":"TypeError: …","occurrences":3412,"users":890,"first_seen":"2026-07-15T…","last_seen":"2026-07-21T…","status":"active"}
  ]}
]}
JSON

This snapshot only powers next week's diff; if it can't be written, the digest still ships — note the write failure in the log and move on.

4b. Write the full report (the digest links to it)

The notification is capped (top ~5 issues + a table); the full report is the complete picture it links to — every issue across every project, with full fields. Write it read-only-safe with a cat heredoc to a stable path under output/ (preserved by the read-only guard). Overwrite it in full each run — it's current-state, not an archive. Copy numbers verbatim from the tool results:

mkdir -p output/posthog-errors
cat > output/posthog-errors/report.md <<'REPORT'
# PostHog errors — full report
_<window> · <M> projects · <N> issues (<new> new) · generated ${today}_

## <project name> — <count> issues · <occurrences> occurrences
### <error title / message>
- <hits> hits · <users> users · <sessions> sessions · <🆕 new | ⬆️ spiking | ongoing | ✅ resolved>
- Source: <file/frame> · first seen <date> · last seen <date> · status <status>
- PostHog: <full issue URL>

… every issue, grouped by project, worst first …
REPORT

Same content discipline as the digest: real fields only, no invented numbers. This file is what the digest's "full report" link opens (built below), so it must be written before the ./notify call.