Optimo Mixpanel Analytics

Overview

Implement or review Optimo backend Mixpanel events and their cross-channel identity and delivery contracts.

This skill ships inside the Mixpanel Analytics plugin and can be installed through the Claude Code marketplace or directly in Codex from its skill path.

Parent Surface

Modes

references/implementation.md. --dry-run produces a proposal only, without editing files or sending events.

references/review.md. Default to staged changes; support an explicit PR/branch, all, or file:path. Inspect only; do not apply fixes or publish review comments without authorization.

• /mixpanel-analytics:implement: follow references/implementation.md. --dry-run produces a proposal only, without editing files or sending events.
• /mixpanel-analytics:review: follow references/review.md. Default to staged changes; support an explicit PR/branch, all, or file:path. Inspect only; do not apply fixes or publish review comments without authorization.

Start With Current Evidence

docs/analytics/optimo-mixpanel/README.md, especially the engineering contract, code map, tests, and current rollout state.

named producer, real callers, and their tests for the affected domain.

It records the guardrails introduced by backend PR #3203 and companion frontend #579; do not resurrect the older implementation templates.

claims. If the local guide is absent, fetch the canonical guide below. If code and guide disagree, report the conflict before an identity or delivery change; never silently restore the old behavior.

Canonical guide: https://github.com/DiversioTeam/Django4Lyfe/blob/dev/docs/analytics/optimo-mixpanel/README.md

Historical rationale: https://github.com/DiversioTeam/Django4Lyfe/pull/3203

Non-Negotiables

$device_id is an independent anonymous merge key, never a browser key. Only the canonical persisted same-tenant relationship may join them.

approved locators. They never choose reserved identity or call private delivery. Producers reload state and derive tenant, subject, and join keys.

frontend owns authenticated browser interactions. Public survey pages emit no frontend Mixpanel events under the current contract.

post-commit and fire-and-forget; analytics failure cannot undo business work.

separate. Preserve trusted impersonation on every event; never identify the impersonated target as the support actor.

text, rendered recommendation titles, or exact risk scores. Disable IP enrichment; normal reports filter impersonation=false.

variants. Use registered origin/person scope and one real occurrence time.

Merge mode is verified and its exact simplified_v1 acknowledgement is set. Never enable telemetry or mutate Mixpanel projects just to make tests pass.

• Permanent human $user_id is OptimoUser.uuid. The backend employee $device_id is an independent anonymous merge key, never a browser key. Only the canonical persisted same-tenant relationship may join them.
• Feature callers use named producers with persisted domain objects or approved locators. They never choose reserved identity or call private delivery. Producers reload state and derive tenant, subject, and join keys.
• One fact has one authority: backend owns authentication and durable outcomes; frontend owns authenticated browser interactions. Public survey pages emit no frontend Mixpanel events under the current contract.
• Register one strict schema, origin, and person scope. Delivery is always post-commit and fire-and-forget; analytics failure cannot undo business work.
• Keep actor, subject, employee, manager, session, and assignment meanings separate. Preserve trusted impersonation on every event; never identify the impersonated target as the support actor.
• No tokens or token hashes, personal content, raw routes, provider/exception text, rendered recommendation titles, or exact risk scores. Disable IP enrichment; normal reports filter impersonation=false.
• Do not reintroduce is_cron_job, cron_execution_timestamp, or cron schema variants. Use registered origin/person scope and one real occurrence time.
• Identity delivery fails closed unless the target project's Simplified ID Merge mode is verified and its exact simplified_v1 acknowledgement is set. Never enable telemetry or mutate Mixpanel projects just to make tests pass.

Type Gate Detection

Read repository typing docs and use its wrappers. Detect ty, then pyright, then mypy; configured ty is mandatory and blocking. Touched files must pass, without blanket suppressions or "baseline acceptable" exceptions. Run the repository's required wider gates before claiming merge readiness.

Resources

Declared allowed tools:

Installation

Switch between Claude Code and Codex, then copy the install command for the runtime you use.

claude plugin marketplace add DiversioTeam/agent-skills-marketplace
claude plugin install mixpanel-analytics@diversiotech

CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
python3 "$CODEX_HOME/skills/.system/skill-installer/scripts/install-skill-from-github.py" \
  --repo DiversioTeam/agent-skills-marketplace \
  --path plugins/mixpanel-analytics/skills/mixpanel-analytics

Invocation:

/mixpanel-analytics:implement
/mixpanel-analytics:review

name: mixpanel-analytics