PostHog Event Naming Convention
What it does
This skill defines the canonical naming convention, property schema, and governance rules for all PostHog analytics events emitted by the legal AI product. Consistent event naming is the prerequisite for building reliable funnels, feature-flag cohorts, and the LLM quality trend dashboard that feeds [[eval-leaderboard-updater]].
Setup / auth
PostHog project is configured via:
POSTHOG_KEY — public client-side key (safe to expose in frontend)
POSTHOG_HOST — self-hosted or app.posthog.com
POSTHOG_SERVER_KEY — server-side key for Edge Function calls (never expose to browser)
All events must include distinct_id (the user's UUID, never email/name in the event itself — PII goes through [[eng-pii-redaction-preprocessor]]).
Capabilities
Naming structure
<noun>_<verb>
- Noun is the product object:
session, skill, document, chat, nda, contract, user, workspace, billing, eval.
- Verb is the past-tense action:
started, completed, failed, viewed, clicked, upgraded, cancelled.
- Always lowercase, words joined with
_.
- No "clicked" or "viewed" as the sole event name — always include a noun:
button_clicked is useless; skill_selector_clicked is queryable.
Event taxonomy
Session & auth
| Event |
When |
session_started |
User opens the app (not page load) |
session_ended |
Tab close or 30-min idle |
user_signed_up |
First auth completion |
user_signed_in |
Every subsequent auth |
user_invited |
Invite link sent |
workspace_created |
New workspace provisioned |
Chat & skill routing
| Event |
When |
chat_message_sent |
User sends any message |
chat_response_received |
First token streamed back |
chat_response_completed |
Stream ends |
skill_routed |
Router resolves a skill |
skill_fallback_triggered |
No skill matched; fell back to generic |
chat_error_occurred |
Any non-2xx from LLM |
Document workflow
| Event |
When |
document_uploaded |
File ingestion starts |
document_indexed |
Embedding complete |
document_reviewed |
Review skill output delivered |
document_drafted |
Draft skill output delivered |
document_downloaded |
User exports a document |
Billing & tier
| Event |
When |
upgrade_prompted |
User hits a tier gate |
upgrade_completed |
Subscription activated |
upgrade_abandoned |
User dismissed upgrade modal |
api_key_saved |
BYO-key entered |
token_budget_exhausted |
Monthly token limit hit |
Eval (server-side only)
| Event |
When |
eval_run_started |
Benchmark run begins |
eval_run_completed |
All rubrics scored |
eval_regression_detected |
Any rubric dropped threshold |
Required properties on every event
{
distinct_id: string; // user UUID
tenant_id: string; // workspace/firm UUID
session_id: string; // current session UUID
platform: "web" | "ios" | "android";
app_version: string; // semver
environment: "production" | "staging" | "local";
}
Per-event additional properties
chat_message_sent
{
message_length_chars: number;
language_detected: "ar" | "en" | "fr" | "mixed";
has_attachment: boolean;
}
skill_routed
{
skill_id: string; // e.g. "draft-nda-unilateral"
skill_category: string; // e.g. "draft"
confidence: number; // router confidence 0-1
latency_ms: number;
}
chat_response_completed
{
skill_id: string;
tokens_input: number;
tokens_output: number;
latency_ms: number;
tier: "free" | "pro" | "business" | "byo";
rubric_score?: number; // if real-time eval enabled
}
Usage patterns
Frontend (React)
import posthog from "posthog-js";
posthog.capture("skill_routed", {
skill_id: routedSkill.id,
skill_category: routedSkill.category,
confidence: routedSkill.confidence,
latency_ms: Date.now() - startTime,
});
Edge Function (server-side)
import { PostHog } from "posthog-node";
const ph = new PostHog(Deno.env.get("POSTHOG_SERVER_KEY")!);
ph.capture({
distinctId: userId,
event: "eval_run_completed",
properties: {
tenant_id: tenantId,
run_id: runId,
aggregate_score: score,
regression_detected: hasRegression,
environment: "production",
},
});
await ph.shutdown();
Permissions & safety
- Never include raw user message content in event properties. Use
message_length_chars instead.
- Never include full names, email addresses, or phone numbers in event properties. Use UUIDs.
environment: "local" events should not appear in the production PostHog project. Gate on env var.
- Billing events (
upgrade_completed) must be cross-validated against Stripe webhook receipts.
Failure modes
| Failure |
Impact |
Mitigation |
Missing tenant_id |
Can't segment by firm |
Assert required properties at emit site via TypeScript type |
| Duplicate events |
Inflated metrics |
Deduplicate on session_id + event + timestamp in PostHog |
| Events in local env polluting production |
Noisy dashboards |
Set environment filter on all saved insights |
| PII in properties |
Privacy violation |
Lint rule: reject any property containing email, name, phone |
Related skills
- [[eng-pii-redaction-preprocessor]] — ensures message content is never passed raw to analytics
- [[eng-token-budget-by-tier]] — tier and budget data feeds
chat_response_completed properties
- [[eval-benchmark-runner]] — consumes
eval_run_* events
- [[eval-leaderboard-updater]] — reads PostHog quality-trend data
1---2name: eng-posthog-event-naming-convention3description: Use when instrumenting user-facing features in the legal AI product with PostHog analytics events. Defines the canonical event taxonomy, naming rules, property schemas, and anti-patterns so that all engineers emit consistent, queryable telemetry that supports product decisions, eval pipelines, and compliance audits.4license: MIT5metadata:6 id: eng.posthog-event-naming-convention7 category: eng8 jurisdictions: [__multi__]9 priority: P210 intent: [__eng__, analytics, posthog, telemetry, events]11 related: [eng-supabase-edge-functions-patterns, eng-token-budget-by-tier, eval-benchmark-runner, eval-leaderboard-updater]12 source: https://skillmd.com/skills/sboghossian-mini-claude-for-legal/eng-posthog-event-naming-convention13 upstream: Louis — HAQQ Legal AI (github.com/sboghossian/mini-claude-for-legal)14 version: "1.0"15---1617# PostHog Event Naming Convention1819## What it does2021This skill defines the canonical naming convention, property schema, and governance rules for all PostHog analytics events emitted by the legal AI product. Consistent event naming is the prerequisite for building reliable funnels, feature-flag cohorts, and the LLM quality trend dashboard that feeds [[eval-leaderboard-updater]].2223## Setup / auth2425PostHog project is configured via:26- `POSTHOG_KEY` — public client-side key (safe to expose in frontend)27- `POSTHOG_HOST` — self-hosted or `app.posthog.com`28- `POSTHOG_SERVER_KEY` — server-side key for Edge Function calls (never expose to browser)2930All events must include `distinct_id` (the user's UUID, never email/name in the event itself — PII goes through [[eng-pii-redaction-preprocessor]]).3132## Capabilities3334### Naming structure3536```37<noun>_<verb>38```3940- **Noun** is the product object: `session`, `skill`, `document`, `chat`, `nda`, `contract`, `user`, `workspace`, `billing`, `eval`.41- **Verb** is the past-tense action: `started`, `completed`, `failed`, `viewed`, `clicked`, `upgraded`, `cancelled`.42- Always lowercase, words joined with `_`.43- No "clicked" or "viewed" as the sole event name — always include a noun: `button_clicked` is useless; `skill_selector_clicked` is queryable.4445### Event taxonomy4647#### Session & auth4849| Event | When |50|---|---|51| `session_started` | User opens the app (not page load) |52| `session_ended` | Tab close or 30-min idle |53| `user_signed_up` | First auth completion |54| `user_signed_in` | Every subsequent auth |55| `user_invited` | Invite link sent |56| `workspace_created` | New workspace provisioned |5758#### Chat & skill routing5960| Event | When |61|---|---|62| `chat_message_sent` | User sends any message |63| `chat_response_received` | First token streamed back |64| `chat_response_completed` | Stream ends |65| `skill_routed` | Router resolves a skill |66| `skill_fallback_triggered` | No skill matched; fell back to generic |67| `chat_error_occurred` | Any non-2xx from LLM |6869#### Document workflow7071| Event | When |72|---|---|73| `document_uploaded` | File ingestion starts |74| `document_indexed` | Embedding complete |75| `document_reviewed` | Review skill output delivered |76| `document_drafted` | Draft skill output delivered |77| `document_downloaded` | User exports a document |7879#### Billing & tier8081| Event | When |82|---|---|83| `upgrade_prompted` | User hits a tier gate |84| `upgrade_completed` | Subscription activated |85| `upgrade_abandoned` | User dismissed upgrade modal |86| `api_key_saved` | BYO-key entered |87| `token_budget_exhausted` | Monthly token limit hit |8889#### Eval (server-side only)9091| Event | When |92|---|---|93| `eval_run_started` | Benchmark run begins |94| `eval_run_completed` | All rubrics scored |95| `eval_regression_detected` | Any rubric dropped threshold |9697### Required properties on every event9899```typescript100{101 distinct_id: string; // user UUID102 tenant_id: string; // workspace/firm UUID103 session_id: string; // current session UUID104 platform: "web" | "ios" | "android";105 app_version: string; // semver106 environment: "production" | "staging" | "local";107}108```109110### Per-event additional properties111112#### `chat_message_sent`113```typescript114{115 message_length_chars: number;116 language_detected: "ar" | "en" | "fr" | "mixed";117 has_attachment: boolean;118}119```120121#### `skill_routed`122```typescript123{124 skill_id: string; // e.g. "draft-nda-unilateral"125 skill_category: string; // e.g. "draft"126 confidence: number; // router confidence 0-1127 latency_ms: number;128}129```130131#### `chat_response_completed`132```typescript133{134 skill_id: string;135 tokens_input: number;136 tokens_output: number;137 latency_ms: number;138 tier: "free" | "pro" | "business" | "byo";139 rubric_score?: number; // if real-time eval enabled140}141```142143## Usage patterns144145### Frontend (React)146147```typescript148import posthog from "posthog-js";149150posthog.capture("skill_routed", {151 skill_id: routedSkill.id,152 skill_category: routedSkill.category,153 confidence: routedSkill.confidence,154 latency_ms: Date.now() - startTime,155});156```157158### Edge Function (server-side)159160```typescript161import { PostHog } from "posthog-node";162const ph = new PostHog(Deno.env.get("POSTHOG_SERVER_KEY")!);163164ph.capture({165 distinctId: userId,166 event: "eval_run_completed",167 properties: {168 tenant_id: tenantId,169 run_id: runId,170 aggregate_score: score,171 regression_detected: hasRegression,172 environment: "production",173 },174});175await ph.shutdown();176```177178## Permissions & safety179180- Never include raw user message content in event properties. Use `message_length_chars` instead.181- Never include full names, email addresses, or phone numbers in event properties. Use UUIDs.182- `environment: "local"` events should not appear in the production PostHog project. Gate on env var.183- Billing events (`upgrade_completed`) must be cross-validated against Stripe webhook receipts.184185## Failure modes186187| Failure | Impact | Mitigation |188|---|---|---|189| Missing `tenant_id` | Can't segment by firm | Assert required properties at emit site via TypeScript type |190| Duplicate events | Inflated metrics | Deduplicate on `session_id + event + timestamp` in PostHog |191| Events in local env polluting production | Noisy dashboards | Set `environment` filter on all saved insights |192| PII in properties | Privacy violation | Lint rule: reject any property containing `email`, `name`, `phone` |193194## Related skills195196- [[eng-pii-redaction-preprocessor]] — ensures message content is never passed raw to analytics197- [[eng-token-budget-by-tier]] — tier and budget data feeds `chat_response_completed` properties198- [[eval-benchmark-runner]] — consumes `eval_run_*` events199- [[eval-leaderboard-updater]] — reads PostHog quality-trend data