Discover Event Surfaces

discover-event-surfaces

You are step 2 of the analytics instrumentation workflow. Read a change_brief YAML and produce an exhaustive candidate list of analytics events — named well, organized by category, and ready for PM review.

Think like an engineer who ships the feature AND cares about whether it succeeds. Generate events that answer product/business questions, not events that mirror implementation details. Aim for breadth and quality — a downstream skill will narrow the list.

Read the taxonomy skill at ../taxonomy/SKILL.md to understand core analytics philosophy and naming standards.

1. Parse the change_brief

• classification.analytics_scope — if none, stop and tell the user there's nothing to instrument.
• summary — one-line description of the change.
• user_facing_changes — primary signal. Each entry = something a user can now do or see differently.
• surfaces.components — modified UI components; where interactions happen.
• file_summary_map — read summaries for files in surfaces or touching user-facing logic. Skip tests/config/tooling.

2. Scan the codebase and map user flows

Before generating any events, build a concrete understanding of how users move through the feature. The change_brief gives you file paths and summaries — now read the actual code to trace the full journey.

What to read

• Every file listed in surfaces.components — read them fully.
• Files from file_summary_map that touch user-facing logic (skip tests, config, tooling).
• Follow imports and references one level out: if a component calls a hook, API function, or navigates to another route, read that target file too. This is how you discover steps the diff didn't touch but that are part of the same flow.

What to look for

Trace the path a user takes from entry to outcome:

• Entry points — how does the user arrive? Route definitions, navigation calls, menu items, links, feature flag gates.
• Interaction sequence — what does the user do step by step? Form fills, selections, confirmations, uploads. Look at handler wiring (onClick, onSubmit, onChange) and what state they mutate.
• Async boundaries — API calls, mutations, server actions. These are where "attempted" becomes "succeeded" or "failed."
• Terminal states — success confirmations, error handling, redirects, completion screens.
• Branching paths — conditionals that route users to different outcomes (e.g., free vs paid, first-time vs returning).

Produce a funnel hypothesis

Synthesize what you found into one or more funnels — ordered sequences of user steps from entry to outcome. Each funnel should have:

• A descriptive name (e.g., "Property extraction flow", "Onboarding wizard")
• The ordered steps, each with the file and function/handler where it happens
• Which step is the start and which is the end

Not every change has a funnel. Single-action features (a toggle, a one-click export) don't need one — just note that there's no multi-step flow. But when a flow exists, mapping it here is what allows you to confidently assign funnel start/end as critical later.

Keep the hypothesis grounded in code you actually read. Don't invent steps you didn't see evidence for.

3. Determine naming conventions and fetch existing events

Invoke discover-analytics-patterns and use its event_naming_convention and property_naming_convention outputs. That skill owns the naming-resolution procedure and precedence order. Do not redefine it here.

Before generating candidates, pull the project's existing event taxonomy so you can avoid duplicates and match the naming convention already in use.

Resolve the project

If the change_brief includes an Amplitude projectId, use it directly. Otherwise, call get_amplitude_context to resolve the project name or ask the user which project to target. You need a projectId for the next call.

Pull existing events

Inspect the connected catalog and use its current taxonomy event reader with the resolved projectId. Follow only its advertised schema. When it supports caller attribution, identify this skill with the name from its YAML frontmatter. No cursor is needed—the first page is enough for pattern detection. Request the event name, category, and description fields when its schema supports field selection, then use the returned field names.

Build naming references and an existing event index

1. Existing event index — Collect all eventType values into a set. You'll check candidates against this set in step 4 to avoid proposing events that are already tracked. An event is a duplicate if its semantic meaning matches an existing eventType, not just its exact string — e.g., if Subscription Upgraded exists, don't propose Plan Upgraded for the same action.

4. Generate candidate events

Start from the funnel hypothesis. If you identified funnels in step 2, generate events for the funnel start and end first — these are your anchors. Then fill in candidates for intermediate steps and non-funnel surfaces.

For each user_facing_change, ask: "If a user does this — what outcomes would a PM want to know about?"

Generate from four categories (ordered by priority):

Deduplicate against existing events

After generating candidates, check each one against the existing event index you built in step 3. For each candidate:

• Exact match — the eventType already exists verbatim. Drop the candidate.
• Semantic match — a different name tracks the same user action or outcome (e.g., you proposed Plan Upgraded but Subscription Upgraded already exists for the same action). Drop the candidate.
• Partial overlap — an existing event covers a broader action that subsumes your candidate (e.g., Checkout Completed already exists and your candidate Payment Submitted fires at the same moment). Drop unless the candidate captures meaningfully different information.

If you drop a candidate because it already exists, note it in a already_tracked list in the output so the user can see what's covered.

5. Quality filter

Every candidate must pass all three:

1. Decision-useful — A PM could make a product decision from this alone, without five other events for context.
2. Outcome-focused — Captures that something happened, not that the user attempted it. Property Extracted > Extract Button Clicked. Prefer confirmed outcomes; form submissions are acceptable when no server confirmation exists.
3. Stable across redesigns — Named around the business/product concept, not the UI element. If renaming a modal would make the event name stale, it's too coupled.

Cut: raw clicks/hovers without outcomes, internal technical actions (API callbacks, state updates), UI-versioned names (modal_v2_submit), sub-step-level granularity.

6. Name events