diagnosing-sdk-health

What this skill does

# Diagnosing SDK health

When a user asks about PostHog SDK versions, outdated SDKs, or whether they should
upgrade, use the pre-digested SDK Doctor report rather than reasoning about versions
yourself. The backend applies smart-semver rules (grace periods, minor-count thresholds,
age-based detection), traffic-percentage thresholds, and provides user-facing copy that
matches the SDK Doctor UI exactly.

## Available tools

| Tool                     | Purpose                                                                                              |
| ------------------------ | ---------------------------------------------------------------------------------------------------- |
| `posthog:sdk-doctor-get` | Returns a structured health report plus UI-matching copy and drill-in URLs per SDK/version.          |
| `posthog:execute-sql`    | (Optional) Run a `sql_query` from the report to show events captured by a specific outdated version. |

## Workflow

### Step 1 — Invoke the tool

```json
posthog:sdk-doctor-get
{}
```

Pass `force_refresh: true` only when the user explicitly asks for fresh data — by default
the report uses a Redis cache that's refreshed every 12 hours.

### Step 2 — Read the top-level summary

```json
{
  "overall_health": "healthy" | "needs_attention",
  "health": "success" | "warning" | "danger",
  "needs_updating_count": 0,
  "team_sdk_count": 0,
  "sdks": [ /* per-SDK assessments */ ]
}
```

Lead with the headline:

- `overall_health: healthy` — everything's current; say so and stop.
- `health: warning` — some SDKs outdated but less than half of the project's SDKs. Flag
  as upgrade recommendations.
- `health: danger` — majority of team SDKs are outdated. Treat as urgent.

### Step 3 — Surface the banner text(s) verbatim

Each SDK's `banners` array contains zero or more sentences that match the SDK Doctor UI's
"Time for an update!" alert exactly, e.g.:

> Version 7.0.0 of the Python SDK has captured more than 10% of events in the last 7 days.

**Quote these verbatim.** They're what the user already sees (or would see) in the UI —
rewording creates drift between agent and product copy.

### Step 4 — Report per-SDK findings

For each entry in `sdks`, surface:

- `readable_name` (e.g. `Python`, `Node.js`, `Web`) — use this in prose, not the raw `lib`
- `latest_version`
- `severity` (`none` / `warning` / `danger`) — use this to group or color findings

Group by severity (`danger` first, then `warning`, then `none`). Skip SDKs with
`needs_updating: false` unless the user explicitly asked about the full state.

### Step 5 — Per-version drill-down (when the user wants detail)

Each SDK's `releases` array has per-version rows. Each row includes UI-matching copy and
ready-to-use links:

- `status_reason` — badge tooltip text that **closely** matches the UI. Quote directly.
  **Caveat**: the relative-age segment
  ("5 months ago" etc.) is computed with Python's `humanize.naturaltime` on the backend
  and JavaScript's `dayjs().fromNow()` in the browser, and the two libraries have
  different thresholds at some boundaries (e.g. humanize says `"30 days ago"` where dayjs
  says `"a month ago"`; humanize says `"4 months ago"` at 148 days where dayjs says
  `"5 months ago"`). The overall template is identical; the age phrasing may be one
  threshold off. If a user cites an exact age from the UI that doesn't match, don't
  "correct" them — the UI is showing dayjs output and both are internally consistent.
- `released_ago` — human-readable relative age (e.g. `"5 months ago"`) — same
  humanize-vs-dayjs caveat as above.
- `is_outdated`, `is_old`, `is_current_or_newer` — booleans if you need to branch
- `sql_query` — complete SQL statement to see the last 50 events captured by this version.
  Suggest it as a copy-paste snippet OR pass it to `posthog:execute-sql` to drill in.
- `activity_page_url` — relative path (starts with `/project/<id>/`) to the Activity >
  Explore page pre-filtered to this lib + version. Combine with the user's PostHog host
  (e.g. `us.posthog.com`) for a clickable link.

### Step 6 — Link to the UI

Always close with a link to the SDK Doctor page: `/project/<project_id>/health/sdk-doctor`.
The UI shows per-row event counts, last-event timestamps, release notes, and SDK docs
links — more than the tool response includes.

## Interpreting severity

The backend applies these rules (you don't need to re-check them):

- **Grace period**: versions released within the last 7 days (14 days for web) are never
  flagged, even if major versions behind.
- **Minor-version rule**: flag if 3+ minors behind OR > 180 days old.
- **Major-version rule**: always flag if a major version behind (outside grace period).
- **Patch-version rule**: never flagged — patch differences are noise.
- **Age rule** (separate "old" flag): desktop SDKs flagged at > 16 weeks old, mobile at
  > 24 weeks old (mobile is more lenient — users don't auto-update apps).
- **Traffic threshold**: an outdated version handling ≥10% of events (≥20% for web)
  surfaces as a traffic alert even if a newer version is also in use. Mobile SDKs are
  excluded from traffic alerts.
- **Overall severity**: `danger` when half or more of the project's SDKs are outdated,
  `warning` when some are outdated but not majority.

## Copy-faithfulness

These response fields are **user-facing UI copy** — quote them verbatim, don't reword:

- `banners[]` — top-level "Time for an update!" alert text. Byte-for-byte match with UI.
- `releases[].status_reason` — per-version badge tooltip text. Template matches the UI,
  but the relative-age phrasing (`"5 months ago"` etc.) can be one boundary threshold
  off because the backend uses `humanize` and the UI uses `dayjs`. See Step 5 caveat.
- `readable_name` — human-readable SDK name. Byte-for-byte match with UI.

`reason` (per-SDK) is a programmatic summary meant for ranking/filtering, not for quoting
to users. Prefer `banners[]` and `status_reason` for user-visible output.

## Handling empty or errored drill-in fields

If `sql_query` or `activity_page_url` comes back as an empty string for a particular
release, the backend sanitizer rejected the `lib_version` as potentially unsafe to
interpolate (e.g. it contained quote characters or whitespace). When this happens:

- **Surface it** — tell the user "the recorded SDK version string doesn't look safe to
  interpolate into a query, so I can't build a drill-in link for it." This is a signal
  worth noting (it could indicate instrumentation tampering or a library bug).
- **Do NOT retry** — calling the tool again won't change the result.
- **Do NOT patch** — don't rewrite the version or guess at a safe substitute and pipe
  that into `posthog:execute-sql`. That would defeat the sanitizer.

Similarly, if you pass `sql_query` to `posthog:execute-sql` and it errors, surface the
error verbatim rather than rewriting the query. The query template is a verbatim mirror
of what the SDK Doctor UI uses — if the UI's SQL wouldn't run, something else is wrong.

**Do not wrap, truncate, or modify `sql_query` in any way before passing to
`posthog:execute-sql`.** No `SELECT * FROM (<sql_query>) LIMIT 10`, no adding `WHERE`
clauses, no changing the ORDER BY, no dropping columns. The query is the verbatim mirror
— if you need something different, build a fresh query from scratch with the user's help,
don't derive it from `sql_query`.

## Deferring to documentation for "why is it still outdated?" questions

When the user expresses confusion about an old SDK version still producing events after
they believed it was updated — phrasings like "I thought I updated", "we already
upgraded", "we deployed the new version but…", "why are users still on the old SDK?",
or any variation of "why isn't it gone?" — do **not** improvise a list of causes. Point
them to the canonical docs page instead:

**https://posthog.com/docs/sdk-doctor/keeping-sdks-current**

That page is the product team's source of truth on why versions persist (HTML s