Event Tracking Specs with AI: From User Story to Taxonomy

Why event tracking gets bolted on instead of specced

A PRD describes what the feature does. A user story describes what "done" looks like. Neither one, by default, describes what you'll measure to know it's working — that question usually only gets asked after launch, when someone wants a number and discovers nobody instrumented the thing that would produce it. By then, adding tracking means a separate ticket, a separate sprint, and a gap in the data for everything that shipped before the fix.

The fix isn't a bigger analytics team. It's treating tracking as part of the spec, written from the same acceptance criteria you already have, at the same time the PRD gets sliced into stories — not as a follow-up nobody remembers to file.

If nobody could answer "how many users hit this?" the week after launch, the feature wasn't fully specced — only the building part was.

This isn't a hypothetical gap. It's the specific moment a PM ends up in front of leadership explaining why a headline number for a shipped feature is "we're still pulling that together" three weeks after launch — which reads as the feature not mattering enough to measure, even when the real story is a missed instrumentation ticket. The credibility cost of that moment is usually higher than the actual engineering cost of speccing the tracking would have been.

Step 0 — What a good event tracking spec actually contains

Four things, per event, no more: a name that follows your existing convention, a trigger (the precise user action or system condition that fires it), the minimum set of properties needed to answer real questions, and the specific question it answers after launch. That last one is the filter that keeps the whole exercise honest — an event with no question behind it is tracking for its own sake.

Step 1 — Ground the agent in your existing taxonomy, not a fresh one

The single most common failure here isn't a missing event — it's an inconsistent one: a new feature ships with checkout_completed when everything else in your warehouse uses order_placed, and now two events mean roughly the same thing to two different teams. Before asking for a spec, put your current convention in context:

• Your existing event naming pattern — verb tense, casing, how objects are named (even a handful of examples is enough)
• The user story or PRD driving this feature, acceptance criteria included
• Any events that already exist nearby in the same flow, so new ones don't duplicate them

Without this, an agent invents something plausible-sounding that fits nothing else in your schema — the same grounding problem covered in why context beats prompts for every other artifact, just with a more expensive failure mode: a naming inconsistency that costs an analytics engineer a full afternoon to untangle months later.

Step 2 — Ask for a taxonomy tied to acceptance criteria, not a wishlist

Here's a starting prompt. The instruction that matters most is tying every proposed event back to a specific acceptance criterion or a specific post-launch question — that's what keeps the list from sprawling:

Read the user story below and our existing event naming
convention in context/product.md first.

For each acceptance criterion, propose the event(s) needed to
verify it happened. For each event:

1. Name — following our existing convention exactly. Don't invent
   a new pattern; extend the one already in use.
2. Trigger — the precise user action or system condition that
   fires it, stated unambiguously enough that an engineer could
   implement it without asking a follow-up question.
3. Properties — the minimum set needed to answer a real question,
   not everything technically available on the object.
4. The question this event answers post-launch. If you can't state
   a specific one, don't propose the event — say so instead.

Flag any acceptance criterion where you don't have enough detail
to define a clean trigger. Ask, don't guess.

User story: [paste it, acceptance criteria included]

Rule 4 is doing the real work: it forces a stated reason for every event before it gets built, which is the cheapest possible moment to cut the ones that don't earn their place. Cutting an event from a spec costs one sentence. Removing one from production, after a dashboard was quietly built on top of it, costs a lot more.

What good output looks like: not "track button_clicked," but something with a stated purpose — "Event: checkout_step_completed. Trigger: user submits the shipping-address form and it passes validation. Properties: step_number, is_guest_checkout. Question this answers: where in the five-step checkout do guest users specifically drop off, since acceptance criterion 3 says guest checkout must not add friction versus logged-in checkout — this is how we'd know if it did." Every field traces back to a decision someone will actually make with the number, not a field that exists because the object happened to have it available.

Step 3 — Tie every event back to a question you'll actually ask

"We might want to know this someday" is not a question — it's how tracking sprawl happens, one reasonable-sounding event at a time, until the schema is full of fields nobody queries and every new engineer has to guess which ones still matter. Push back on any proposed event that can't name a specific consumer: "who asks this question, and how often?" If the honest answer is "nobody, but it seemed useful," cut it. You can always add an event later when a real question shows up. You can rarely clean up a warehouse full of ones that didn't.

This discipline compounds in a way that isn't obvious the first time you apply it. A schema with twelve well-justified events per feature stays legible for years — anyone can open it and understand what each one is for. A schema with forty loosely-justified events per feature becomes archaeology within a year: nobody remembers why half of them exist, deprecating any of them feels risky because someone somewhere might depend on it, and the actual signal gets harder to find every quarter it's left unpruned.

Step 4 — Hand off a spec engineering can build from directly

The output should read like part of the ticket, not a separate analytics wishlist attached after the fact — instrumentation built alongside the same user stories it's meant to measure, so "did we ship the tracking" is answered by the same Definition of Done as "did we ship the feature." This closes the loop the decision brief and leadership update both eventually depend on: numbers you can actually produce when someone asks, not a promise to go check.

Add one more habit and this stops being a one-time fix: revisit the taxonomy alongside the epic it belongs to, not just the individual story. Related features tend to want related events, and catching the overlap at the epic level — before three separate stories each invent a slightly different way to measure the same underlying thing — is a lot cheaper than reconciling three inconsistent events after they've all shipped.

Common mistakes to avoid

• Speccing tracking after launch. By then it's a separate ticket competing for sprint capacity against whatever's next, and the data gap for everything already shipped is permanent.
• Inventing a new naming convention per feature. Every inconsistency is a future afternoon lost to reconciling two events that mean the same thing.
• Tracking without a stated question. An event nobody will query is a maintenance cost with no offsetting value.
• Over-specifying properties. Capturing everything technically available "just in case" bloats the schema and rarely gets used.
• Treating the spec as engineering's problem alone. The PM knows which questions matter; engineering knows what's feasible to capture. Neither should draft this alone.

FAQ