---
name: verify-posthog-instrumentation
description: >
  Use this skill to verify that PostHog instrumentation is firing correctly on
  a website. Drives a real browser at one or more URLs, observes which PostHog
  events actually arrive, and reports a pass/fail summary. Use after installing
  the PostHog SDK on a site, after a deploy that touches tracking code, or when
  events appear missing in the PostHog dashboard.
---

# Verify PostHog instrumentation

End-to-end check that the PostHog SDK is loaded and emitting events as expected.
This skill orchestrates the three traffic-sim tools to give a complete picture
of a site's instrumentation health.

## When to use

- After running `npx @posthog/wizard` to confirm the install actually works.
- After a deploy that touches analytics, tracking, or layout code.
- When a customer reports "I'm not seeing events in PostHog" — to disambiguate
  between snippet issues, network issues, or filtering issues.
- As a smoke test before launching a new site or marketing page.

## Workflow

### Step 1 — Confirm the snippet is loaded everywhere

Run the `check_posthog_loading` MCP tool against the URLs you care about
(homepage, key product pages, login, checkout, marketing pages). It returns
which pages have PostHog initialized, the load method (head_snippet / snippet
/ array_js_only), and the init config.

Look for:

- Pages where `loaded: false` — PostHog is missing from those pages.
- Inconsistent `api_key` values across pages — multiple projects in use.
- Inconsistent `api_host` values across pages — events going to different ingestion endpoints.

### Step 2 — Send synthetic traffic and confirm events arrive

Pick one URL where Step 1 confirmed PostHog is loaded. Call:

- `simulate_new_user` — a few fresh-browser visits. Confirms `$pageview`
  fires for first-time visitors and that an anonymous distinct_id is assigned.
- `simulate_returning_user` — a few page views in a single session. Confirms
  cookies persist and `$pageview` keeps firing across navigations.

The tools return `verified: true` when at least one `$pageview` was captured
and there were no errors.

### Step 3 — Cross-check in PostHog

If Steps 1 and 2 pass but events don't show up in the PostHog UI, the issue
is downstream of the snippet:

- Check for ingestion lag (events can take ~30s to appear).
- Check that the `api_host` matches the project's ingestion host.
- Check feature flag and ingestion warnings in the PostHog UI.

## What "verified" means in this skill

A site is verified when:

1. `check_posthog_loading` reports `loaded: true` on every URL we expect.
2. `simulate_new_user` and `simulate_returning_user` both return at least one
   `$pageview` event per visit, with no errors.
3. (Optional) The events appear in the PostHog UI within 1-2 minutes.

## What this skill does not check

- Whether your custom events (e.g. `signup_completed`) are being sent —
  the tool watches for any PostHog event, but you'd need to drive the actual
  user flow to see custom events fire. Use it as a starting point, then add
  user-flow simulation on top.
- Server-side ingestion. The tool only sees what the browser SDK sends.
- Session recording quality. The tool reports whether recording is enabled
  in the init config but doesn't validate the recording itself.