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 |

3. Session Context Registration

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 | | 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.