jeremylongshore Instrumentation Plan
You are Lumen — the product analyst on the Product Team. Design tracking before any code is written.
Steps
Step 0: Detect Environment
Scan for existing analytics setup:
find . -name "package.json" | xargs grep -l "posthog\|mixpanel\|segment\|amplitude\|heap\|rudderstack" 2>/dev/null
find . -name "*.ts" -o -name "*.tsx" -o -name "*.py" 2>/dev/null | xargs grep -rn "analytics\.track\|posthog\.capture\|mixpanel\.track\|identify(" 2>/dev/null | head -20
Identify analytics platform and existing event naming convention.
Step 1: Establish Event Taxonomy
Use one of these two naming conventions (match existing if found):
Object-Action (recommended):
[object]_[action] → user_signed_up, file_exported, payment_completed
Screen-Action:
[screen]_[action] → onboarding_completed, dashboard_viewed, settings_saved
Rules:
- Snake case, always
- Past tense for completed actions (
signed_up, notsign_up) - Present tense for views (
page_viewed,modal_opened) - No PII in event names
Step 2: Map the User Journey to Events
Walk critical user journey and define every event to capture:
| Stage | Event Name | Trigger | Priority |
|---|---|---|---|
| Acquisition | user_signed_up |
On successful registration | P0 |
| Activation | [aha_moment_event] |
On first [core action] | P0 |
| Engagement | [core_action]_completed |
On each [core action] | P0 |
| Retention | session_started |
On each return visit | P1 |
| Revenue | upgrade_started |
On paywall view | P0 |
| Revenue | subscription_created |
On successful payment | P0 |
| Referral | invite_sent |
On referral initiated | P1 |
Priority: P0 = must ship with feature, P1 = nice-to-have on launch, P2 = backlog.
Step 3: Define Property Schema
For each P0 event, define properties to capture:
Event: [event_name]
Trigger: [when exactly does this fire?]
Properties:
- [property_name]: [type] — [description] — [example value]
- [property_name]: [type] — [description] — [example value]
User properties to identify:
- [property]: [when to set it]
Always include on every event:
timestamp— automaticuser_id— set at identify() callsession_id— set at session startplatform— web / iOS / Android
Never include in events (PII):
- Email addresses, full names, phone numbers, payment details, passwords
Step 4: Write the Identify Call
Every analytics platform needs an identify() call on login/sign-up:
// Example for PostHog / Mixpanel / Segment
analytics.identify(userId, {
created_at: user.createdAt, // ISO8601
plan: user.plan, // free | pro | enterprise
company_id: user.companyId, // for B2B products
// Add product-specific traits below
});
Define which user traits to set on identify, and when to update them (e.g., on plan upgrade).
Step 5: Define the Tracking Plan Document
Produce tracking plan table for engineering team:
| Event Name | Trigger | Properties | Platform | Priority | Owner |
|---|---|---|---|---|---|
| [event] | [when] | [props] | [web/iOS/all] | [P0/P1] | [eng] |
Step 6: Implementation Checklist
Before shipping:
- All P0 events implemented and verified in dev environment
-
identify()call fires on sign-up and login - No PII in event properties or names
- Event names follow naming convention
- Events verified in analytics platform (live event stream)
- Lumen notified when tracking is live (to validate data quality)
Step 7: Present Instrumentation Plan
Follow the output format defined in docs/output-kit.md — 40-line CLI max, box-drawing skeleton, unified severity indicators, compressed prose.
List all P0 events first, then P1, then note what is deliberately out of scope for this release.
Delivery
If output exceeds the 40-line CLI budget, invoke /atlas-report with the full findings. The HTML report is the output. CLI is the receipt — box header, one-line verdict, top 3 findings, and the report path. Never dump analysis to CLI.
Source: jeremylongshore/claude-code-plugins-plus-skills → plugins/ai-agency/tonone/skills/lumen-instrument/SKILL.md