Product Analytics - Instrumentation & Measurement OS

Modern Best Practices (January 2026): PostHog-first, session context registration, strict event naming, North Star activation events, privacy-first attribution.

Primary sources live in data/sources.json . If web search is available, refresh time-sensitive details against official docs before giving definitive advice.

No fluff. Only executable steps, templates, and checklists.

When to Use This Skill

• Event taxonomy design: Naming conventions, event hierarchy, property structure

• Tracking plan creation: What to track, where, and why

• Marketing attribution: UTM capture, campaign tracking, source attribution

• Activation metrics: Defining and measuring user activation

• Retention analysis: Cohort analysis, churn prediction, engagement scoring

• Platform setup: PostHog, Pendo, Amplitude, Mixpanel, Heap configuration

• Data quality: Event validation, debugging, governance

Default Workflow (Use Unless User Overrides)

• Clarify goals and constraints: business questions, lifecycle stages, identity model, privacy/consent requirements, platforms (web/mobile/backend).

• Define the North Star value event: one canonical event that represents value received (plus the smallest set of supporting events).

• Write the tracking plan: use assets/tracking-plan-saas.md as the starting template; define required properties and ownership.

• Implement instrumentation: pick the platform guide in Quick Reference (PostHog/Pendo/Amplitude/Mixpanel/Heap; server-side if needed).

• QA and harden: use assets/analytics-qa-checklist.md

• references/event-quality-rules.md
• references/production-hardening.md .

Core Principles

1. North Star Value Event (VITAL)

Every product must have ONE canonical activation event - the single event that means "user received real value."

Product Type North Star Event When It Fires

Content/Media content_consumed

Content fully loaded and visible

SaaS Tool workflow_completed

User completes core workflow

E-commerce purchase_completed

Transaction successful

Developer Tool integration_working

First successful API call

Rule: Every feature event should collapse into ONE activation event with properties:

// PASS CORRECT: One event, differentiated by property posthog.capture('value_delivered', { value_type: 'report', value_id: 'rpt_123' }); posthog.capture('value_delivered', { value_type: 'integration', value_id: 'int_456' });

// FAIL WRONG: Fragmented "value" events (harder to unify in retention/funnels) posthog.capture('report_generated'); posthog.capture('integration_working');

2. Minimum Viable Analytics (MVA)

Start with 5-15 events, not 200. You can always add more.

Layer Required Events Optional

Acquisition page_viewed , signup_completed

campaign_landed

Activation Your activation event (1-2 max) onboarding_step_completed

Engagement Your engagement signal (1-2 max) feature_used

Conversion purchase_completed

checkout_started

For auth-heavy products, add email reliability instrumentation early:

• auth_email_requested (type: signup_confirm, magic_link, reset_password)

• auth_email_delivered / auth_email_bounced / auth_email_complained (from provider webhooks)

• auth_email_link_clicked (completion quality signal, not just send volume)

3. Session Context Registration

Register standard context once per session using posthog.register() :

posthog.register({ app_env: 'prod', platform: 'web', landing_path: window.location.pathname, traffic_source: deriveTrafficSource(), utm_source, utm_medium, utm_campaign });

4. Event Naming Convention

Rule Correct Incorrect

Lowercase only user_signed_up

User_Signed_Up

Snake_case button_clicked

buttonClicked

Object_action format project_created

createProject

Quick Reference

Task Reference

PostHog setup references/posthog-implementation.md

Pendo setup references/pendo-implementation.md

Amplitude setup references/amplitude-implementation.md

Mixpanel setup references/mixpanel-implementation.md

Heap setup references/heap-implementation.md

Server-side tracking references/server-side-tracking.md

Privacy compliance references/privacy-compliance.md

Event quality rules references/event-quality-rules.md

Production patterns references/production-hardening.md

Funnel analysis references/funnel-analysis.md

Cohort retention references/cohort-retention-analysis.md

Experimentation references/experimentation-framework.md

User segmentation references/user-segmentation.md

Data governance references/data-governance.md

Session replay & heatmaps references/session-replay-heatmaps.md

Attribution modeling references/attribution-modeling.md

Tracking plan template assets/tracking-plan-saas.md

UTM standards assets/utm-naming-standards.md

Implementation Checklist

Event Correctness

• Activation event fires only when value is visible (not on mount)
• Event includes required properties defined in the tracking plan (e.g., object_type, object_id, surface, flow)
• Dedupe guard used where re-renders can double-fire (see references/production-hardening.md)
• Event fires in exactly one place per feature

Session Context

• registerSessionContext() called on app init
• Includes: app_env, platform, landing_path, traffic_source, UTMs

Type Safety

• TrafficSource uses TypeScript enum, not free string
• All properties use snake_case

Privacy

• Person properties contain no PII by default
• Email only stored with explicit consent

Decision Tree

Not seeing expected events?

├─ PostHog default events visible? ($pageview, autocapture) │ ├─ Yes -> Custom event bug -> Check component, guards, dedupe │ └─ No -> SDK issue -> Check env vars, consent, ad blockers ├─ Check DevTools Network -> verify /e/ calls └─ Check PostHog Live Events (not Activity)

Can't answer business questions?

├─ Missing events -> Add custom events for key moments ├─ Missing properties -> Enrich with context ├─ No user ID -> Implement identify() calls └─ Attribution gaps -> Capture UTMs, persist through signup

Anti-Patterns Summary

Anti-Pattern Instead

No North Star event Define ONE canonical activation event

Excessive *_viewed events Collapse into one event with properties

PII in identify() State-based identification only

Event spam from re-renders Use isPostHogReady() guard + dedupe

Free text source

Use TypeScript enum for TrafficSource

Non-unique IDs Use stable domain IDs (*_id ) or an action_instance_id

Tracking everything Focus on 5-15 key events (MVA)

Inconsistent naming Enforce lowercase snake_case strictly

See references/event-quality-rules.md for detailed examples.

Metrics and Benchmarks

Default to internal baselines and trendlines; use external benchmarks only when comparing like-for-like segments and definitions.

If you need external references, see data/sources.json -> benchmarks_research .

Templates

Template Purpose

tracking-plan-saas.md Complete SaaS tracking plan

marketing-event-library.md Marketing attribution events

utm-naming-standards.md UTM parameter guide

activation-metrics-template.md Activation metric definition

analytics-qa-checklist.md Data quality checklist

International Markets

This skill uses US/UK market defaults. For international product analytics:

Need See Skill

Regional compliance (GDPR, PIPL, LGPD) marketing-geo-localization

Regional analytics platforms (Baidu Analytics) marketing-geo-localization

Privacy requirements by region marketing-geo-localization

Cookie consent by jurisdiction marketing-geo-localization

If your query is primarily about GDPR/PIPL/LGPD or consent configuration, use marketing-geo-localization alongside this skill.

Related Skills

• marketing-cro - A/B testing, conversion optimization

• marketing-leads-generation - Lead funnel, B2B attribution

• qa-agent-testing - LLM agent testing (complements AI analytics)

• data-sql-optimization - SQL for analytics queries

Data Sources

See data/sources.json for official documentation links.

Ops Runbook: Instrumentation Gate (Pre-PR)

Use this to keep analytics changes production-safe and queryable.

Pre-PR Commands

1) Find changed tracking calls

rg -n "capture(|track(|analytics.|posthog." src app lib

2) Enforce event/property naming policy

rg -n "[A-Z]" src | rg "capture(|track(" # quick camelCase/PascalCase smell

3) Validate tracking plan coverage

(keep a single source of truth file; fail if event is missing)

rg -n "signup_started|signup_completed|checkout_started|trial_started" docs src

4) Run analytics gate test (if project defines one)

npm run test:analytics-gate

Post-Deploy Smoke Query Template

-- Replace table names for your warehouse/provider select event, count(*) as events, count(distinct distinct_id) as users from events where timestamp >= now() - interval '24 hour' and event in ('signup_started','signup_completed','checkout_started','trial_started') group by event order by events desc;

Event Contract Minimum

Each critical event must include:

• stable event name (snake_case)

• actor id (user_id or distinct_id )

• object id (*_id )

• source context (surface , entry_point , utm_* when relevant)

• timestamp from server or trusted client clock

Gate Failure Policy

• Missing critical event or required property: block merge.

• Non-critical property drift: allow merge only with follow-up issue.

• Silent event rename: block merge until dashboard/query migration is prepared.