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)

1. Clarify goals and constraints: business questions, lifecycle stages, identity model, privacy/consent requirements, platforms (web/mobile/backend).
2. Define the North Star value event: one canonical event that represents value received (plus the smallest set of supporting events).
3. Write the tracking plan: use assets/tracking-plan-saas.md as the starting template; define required properties and ownership.
4. Implement instrumentation: pick the platform guide in Quick Reference (PostHog/Pendo/Amplitude/Mixpanel/Heap; server-side if needed).
5. 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.