Draft Tracking Specs in Your Org's Event Taxonomy

Workflow area: Analytics & Experimentation · Tier: Foundation · Hands-on time: ~30 minutes

Instrumentation is specified at the worst possible moment: end of the build, in a hurry, by pattern-matching against whatever events already exist. The result is approvalSubmitted living next to expense_approved and Submit_Approval_v2, and a funnel analysis six months later that silently misses a third of the traffic. AI is genuinely good at both halves of the fix: enumerating what a feature needs tracked, and holding fifty existing event names in mind while naming the new ones consistently.

When to use — and when not to

• Use it at PRD time, not launch timedraft the tracking spec when acceptance criteria are drafted (pb-07); events specified after build are events you'll wish were different.
• Use it when the metrics tree needs feedingpb-05's north-star inputs are only measurable if some event, with some property, fires at the right moment; this is where that becomes real.
• Use it for taxonomy hygiene on inherited productsthe drift check run against an existing event export is a health report you can hand data engineering.
• Skip it if no taxonomy exists yetnaming conventions are a data-team decision with long-lived consequences; agree object-action vs action-object and casing with them first, then automate compliance with it.
• Skip the temptation to track everythingAI will happily enumerate forty events per feature; events without an intended question attached are storage costs and privacy surface.

The recipe

1. 1.

   Export the current taxonomy. Pull the event and property list from Amplitude, Mixpanel, Avo, or your Segment tracking plan — names, properties, and (if available) descriptions. This is the model's style guide; without it you'll get generically sensible names that match nothing you have.

2. 2.

   Draft the spec against the taxonomy. In Claude or ChatGPT:

   Copy

   Draft an event tracking spec for this feature, strictly following
   our existing taxonomy's conventions.
   
   Feature spec: [PASTE PRD SECTION / STORIES]
   Questions we need to answer: [e.g. "adoption of bulk approval;
   where the flow drops off; effect on time-to-approve"]
   Existing taxonomy: [PASTE EVENT + PROPERTY EXPORT]
   
   For each proposed event:
   - name (matching our convention EXACTLY — infer the convention
     from the export and state what you inferred)
   - trigger: precise user/system action, including NON-triggers
     (e.g. "fires on server confirm, not button click")
   - properties: name, type, allowed values, example
   - which question above it serves
   
   Rules: reuse an existing event with a new property over creating a
   near-duplicate event — flag every such reuse for review. Do not
   propose events that serve no listed question. List open decisions
   (identity, consent gating, sampling) separately for humans.
   

3. 3.

   Check the convention the model inferred. Good output leads with:

   Copy

   Inferred convention: object_action, snake_case, past tense
   (expense_submitted, report_exported); properties camelCase.
   
   EVENTS
   expense_bulk_approved
   - Trigger: server confirms batch approval (NOT on click; partial
     failures fire expense_bulk_approve_failed instead)
   - Properties: batchSize (int, 2-50), queueAgeDays (float),
     approverRole (enum: admin|manager)
   - Serves: adoption, time-to-approve
   REUSE FLAG: consider expense_approved + isBulk property instead —
   pro: funnel continuity; con: batchSize semantics. Decision needed.
   

   If the inferred convention is wrong, your export has drift worth fixing — which is its own finding. Decide every REUSE FLAG yourself: reuse-vs-new-event determines whether historical funnels keep working, and that's a product-analytics judgment, not a naming one.

4. 4.

   Run the drift check as a separate pass. "Compare my proposed events against the existing taxonomy: list any naming inconsistencies, near-duplicates of existing events, or property-name collisions where the same concept has different names (userRole vs approverRole)." Fix what it finds; this two-minute pass is the difference between a taxonomy and a pile.

5. 5.

   Walk the triggers against the actual UX flow. For each event, point at the exact moment in the design where it fires, and confirm the edge cases: does the event fire on retry? on partial failure? on back-button? Trigger ambiguity — not naming — is the number-one source of wrong dashboards, and only someone who knows the flow can resolve it.

6. 6.

   Hand to data engineering as a draft. They own identity resolution, consent gating, delivery guarantees, and the final word on the plan. Your spec arriving consistent and question-driven is what makes that review fast.

Make it yours

• Avo or Segment Protocols as the enforcement layer: paste the approved spec into your tracking-plan tool so the convention is machine-checked at instrumentation time — the AI drafts compliance, the tool enforces it.
• Claude Project as the living taxonomy home: keep the current event export and naming rules as project knowledge; every new feature's spec request is then two lines, and the drift check runs against the same source of truth every time.
• Team scale: run the drift check quarterly over the full production taxonomy, not just new specs — the ranked inconsistency report is the agenda for a 30-minute cleanup with data engineering that saves days of analysis pain later.

Quality check

• Every event answers a named questionorphan events cut; if you can't say what dashboard reads it, it doesn't ship.
• Names verified against the real exportspot-check five proposed names against the actual taxonomy yourself; the model occasionally "corrects" your convention to a more common one.
• Triggers are unambiguous at the edgesretry, failure, and abandon behavior specified for every event; "fires on approval" is not a trigger.
• Property values are boundedenums enumerated, ranges stated; free-text properties are where PII sneaks into analytics.
• Data engineering reviewed ita tracking spec nobody with pipeline knowledge approved is a hypothesis, not a plan.