discover-event-surfaces

bởi amplitude

Với một change_brief YAML (đầu ra từ diff-intake), tạo danh sách đầy đủ các sự kiện phân tích tiềm năng cần được instrument. Tiếp cận từ góc nhìn của một kỹ sư có tư duy của PM — nêu ra mọi thứ đáng cân nhắc để PM quyết định điều gì thực sự quan trọng. Dùng kỹ năng này ở bước 2 của quy trình instrument phân tích, ngay sau khi diff-intake tạo ra change_brief. Kích hoạt bất cứ khi nào người dùng có change_brief YAML và muốn biết cần thêm những sự kiện phân tích nào, hoặc hỏi "what...

npx skills add https://github.com/amplitude/mcp-marketplace --skill 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):

CategoryWhat it capturesWhen to include
business_outcomeRevenue, retention, growth actions (purchases, subscription changes, conversion gates)Change touches monetization or retention surface
user_journeyMeaningful state transitions (workflow completed, feature activated, onboarding finished)Change introduces or alters a user journey step
feature_successThe "it worked" moment — confirmed outcome, not button click (document created, report generated)Any new or materially changed feature
friction_failureWhere users fail, get stuck, or give up (errors, empty states, abandonment)Complex multi-step interactions or error-prone flows

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

Use the naming conventions returned by discover-analytics-patterns. New events should look like they belong with the rest of the instrumentation: same casing, same word order, same delimiters, same prefix patterns, and the same level of specificity.

If you later need to suggest property names in rationale or instrumentation hints, use the property_naming_convention returned by discover-analytics-patterns.

In all cases, use product-domain subjects (Property, User, Document), not code names (PropertyItem, ActionStore).

Good (Title Case convention)Bad
Property Extractedextract_property_clicked
Extract Type Configuredtype_dropdown_changed
Property Creation Failed500_error_new_property

7. Determine file and instrumentation point

For each candidate, use file_summary_map and surfaces.components to identify:

  • file — the source file where the tracking call belongs. Prefer the file closest to where the outcome is confirmed (not where the user initiates the action). Usually a component file from surfaces.components or a hook where an async operation resolves.
  • instrumentation — 1-2 sentences: when it fires (after what condition/callback/state transition) and how it's wired (which function/handler to place it in). Reference actual function names from file summaries so an engineer can find the right line.

8. Deepen understanding, then prioritize

For each candidate, first work through these two fields — they force you to think concretely about the event's value before scoring it:

  • analysis_recipe — Describe the specific chart, funnel, or query an analyst would build with this event. Be concrete: mention the visualization type, segmentation dimensions, and any other events to combine with. e.g., "Weekly funnel: Panel Opened → Extract Type Selected → Property Extracted, segmented by extractType. Alert if completion rate drops below 50%."
  • stakeholder_narrative — Write a sentence that a PM could drop into a quarterly review or board deck, using this event's data. Imagine the metric already exists and write the story it tells. e.g., "68% of users who try extraction complete it on the first attempt, up from 45% last quarter." If you can't imagine a compelling slide sentence, the event probably isn't worth instrumenting.

Now, with that context fresh, assign a priority:

PriorityMeaningGuidance
3 (critical)You would block a release if this event were missing. It answers a question the team will ask in the first week.Reserve for events that directly measure whether the feature succeeded or failed. Most changes produce only 1-2 critical events.
2 (useful)Adds real analytical value but the feature can ship without it. Worth adding if instrumentation cost is low.Segmentation dimensions, secondary workflows, configuration choices.
1 (optional)Nice-to-have. Only instrument if the team has bandwidth and a specific hypothesis to test.Edge-case failures, exploratory engagement signals, discoverability metrics.

Funnel events deserve special attention. When a change introduces or modifies a multi-step process (checkout flow, onboarding wizard, data import pipeline), the PM's first question will be "where are users dropping off?" A gap between funnel start and funnel end with no visibility in between is a blind spot that can hide serious product problems — if engagement craters at step 2 of 5, the team needs to know, not guess.

Funnel start and funnel end events are always critical (priority 3). Without the bookends, you can't measure conversion rate — the single most important metric for any funnel. These two events are non-negotiable regardless of funnel length or complexity.

To decide how many intermediate funnel events to mark critical, gauge the length and complexity of the funnel:

  • Short process (2-3 steps, single page): The start and end events are enough. Don't instrument every micro-step in a simple flow.
  • Medium process (3-5 steps, possibly spanning pages): Add one intermediate event at the most likely drop-off point — typically where the user commits effort (fills a form, makes a key selection, uploads a file).
  • Long process (5+ steps, multi-page or wizard-style): 2-3 intermediate events at natural phase boundaries. Think "started → configured → submitted → confirmed" rather than tracking every field interaction.

Be selective with intermediate events. Every funnel event you mark critical is one more thing an engineer must implement and a PM must monitor. If you're unsure whether an intermediate step is worth tracking, it probably isn't — the start and end events will reveal whether there's a problem, and the team can always add granularity later once they see where drop-off is high.

Less is more. A focused set of critical events that actually get dashboarded beats a sprawling list nobody looks at. When in doubt, downgrade — it's easier to add an event later than to remove one that's already in dashboards.

9. Emit YAML output

Output only the YAML block — no surrounding prose.

event_candidates:
  source_summary: "<from change_brief.summary>"
  analytics_scope: "<from change_brief.classification.analytics_scope>"
  event_naming_convention: "<from MCP if clear, otherwise codebase instrumentation, otherwise taxonomy skill>"
  property_naming_convention: "<from MCP if clear, otherwise codebase instrumentation, otherwise taxonomy skill>"

  already_tracked:                         # omit if no duplicates found
    - existing_event: "Subscription Upgraded"
      candidate_dropped: "Plan Upgraded"
      reason: "Same action — existing event already tracks plan/subscription upgrades."

  funnels:                                 # omit if no multi-step flows found
    - name: "Descriptive funnel name"
      steps:
        - step: "Step description"
          file: "src/components/Foo.tsx"
          function: "handleOpen"
          role: start                      # start | intermediate | end
        - step: "Next step"
          file: "src/components/Bar.tsx"
          function: "onSubmit"
          role: intermediate
        - step: "Final step"
          file: "src/hooks/useSave.ts"
          function: "onSuccess"
          role: end

  candidates:
    - name: "Event Name Here"
      category: feature_success          # business_outcome | user_journey | feature_success | friction_failure
      rationale: "What PM question this answers."
      analysis_recipe: "Weekly trend of completions; funnel from Panel Opened → Extract Type Selected → Event Name, segmented by extract type."
      stakeholder_narrative: "Feature X adoption reached 40% of active users within two weeks of launch, exceeding our 25% target."
      priority: 3                        # 3 = critical, 2 = useful, 1 = optional
      funnel: "Funnel name"             # which funnel this belongs to, if any
      funnel_role: start                 # start | intermediate | end — omit if not part of a funnel
      surface: "ComponentName"           # from surfaces.components
      file: "src/components/Foo/Bar.tsx"
      instrumentation: "Fire after the async save resolves, inside onSuccess of useExtract(). Pass result status."

    - name: "Another Event"
      category: user_journey
      rationale: "..."
      analysis_recipe: "..."
      stakeholder_narrative: "..."
      priority: 2
      surface: "..."
      file: "..."
      instrumentation: "..."

Order: higher categories first, most impactful within each category first.


Example

Input excerpt:

user_facing_changes:
  - "Users can now select Extract Type (Text or Attribute) in the PropertyItem panel"
surfaces:
  components:
    - name: PropertyItem
      change: modified

Good candidates:

- name: "Property Extracted"
  category: feature_success
  rationale: "Core adoption signal — tells PMs whether the extract workflow completes."
  analysis_recipe: "Weekly funnel: Panel Opened → Extract Type Selected → Property Extracted, segmented by extractType. Alert if completion rate drops below 50%."
  stakeholder_narrative: "72% of users who open a property panel complete an extraction, up from 0% before this release — validating the new extract workflow."
  priority: 3
  surface: "PropertyItem"
  file: "src/components/PropertiesPanel/PropertyItem.tsx"
  instrumentation: "Fire after extract resolves successfully in onSuccess handler. Include extractType (TEXT or ATTRIBUTE)."

- name: "Extract Type Selected"
  category: feature_success
  rationale: "Shows which mode users prefer — informs investment in Attribute mode."
  analysis_recipe: "Pie chart of Text vs Attribute selections over 30 days. Combine with Property Extracted to get per-mode completion rate."
  stakeholder_narrative: "85% of extractions use Text mode vs 15% Attribute — we should double down on Text UX before expanding Attribute capabilities."
  priority: 2
  surface: "PropertyItem"
  file: "src/components/PropertiesPanel/PropertyItem.tsx"
  instrumentation: "Fire in onChange of Extract Type select, passing new value."

- name: "Property Extraction Failed"
  category: friction_failure
  rationale: "Surfaces where the extract workflow breaks for reliability prioritization."
  analysis_recipe: "Error rate chart: Property Extraction Failed / (Property Extracted + Property Extraction Failed), grouped by error reason. Alert on spikes."
  stakeholder_narrative: "Extraction failure rate dropped from 12% to 3% after the v2 error-handling patch — users are hitting fewer dead ends."
  priority: 2
  surface: "PropertyItem"
  file: "src/components/PropertiesPanel/PropertyItem.tsx"
  instrumentation: "Fire in catch/onError of extract call. Include error reason if available."

Do NOT include: Extract Type Dropdown Opened (click, no outcome), PropertyItem State Updated (internal), Attribute Input Focused (too granular).

Thêm skills từ amplitude

add-analytics-instrumentation
amplitude
Quy trình triển khai instrumentation analytics từ đầu đến cuối cho một PR, nhánh, tệp, thư mục hoặc tính năng. Đọc mã, xác định các sự kiện cần theo dõi và tạo kế hoạch instrumentation cụ thể — tất cả chỉ trong một lần. Dùng skill này bất cứ khi nào người dùng muốn thêm analytics vào một PR, yêu cầu “instrument this PR”, “add tracking to this branch”, “what analytics does this file need”, “instrument the checkout flow”, “run the full instrumentation workflow” hoặc bất kỳ yêu cầu nào hàm ý thực hiện toàn bộ quy trình từ mã...
developmentdata-analysisapi
diff-intake
amplitude
Đọc diff của PR hoặc nhánh và tạo bản tóm tắt thay đổi có cấu trúc bằng YAML để các kỹ năng instrument analytics ở bước sau sử dụng. Hãy dùng kỹ năng này làm bước đầu tiên khi người dùng chia sẻ liên kết PR, so sánh nhánh hoặc diff thô và muốn tìm hiểu những gì đã thay đổi, cần theo dõi những gì hoặc cách instrument một tính năng. Kích hoạt khi gặp các cụm từ như “review PR này”, “nhánh này đã thay đổi những gì”, “giúp tôi instrument diff này”, “kiểm tra mức độ bao phủ analytics cho thay đổi này” hoặc bất kỳ yêu cầu nào muốn bắt đầu đánh giá analytics...
developmentcode-reviewdata-analysis
discover-analytics-patterns
amplitude
Khám phá cách các lệnh gọi theo dõi phân tích thực sự được viết trong codebase này — các lệnh gọi SDK cụ thể, chữ ký hàm và mẫu import được dùng để gửi sự kiện. Hãy dùng skill này bất cứ khi nào bạn cần hiểu các mẫu tích hợp phân tích hiện có trước khi thêm tính năng theo dõi mới, khi ai đó hỏi “ở đây chúng ta theo dõi sự kiện như thế nào?”, “cho tôi xem thiết lập phân tích”, “mẫu phân tích trong codebase này là gì?”, hoặc bất cứ khi nào các skill instrument-events hoặc discover-event-surfaces đề cập đến...
developmentdata-analysisapi
instrument-events
amplitude
Với YAML event_candidates (đầu ra từ discover-event-surfaces), tạo kế hoạch instrumentation cụ thể cho các sự kiện priority-3 (critical). Hoạt động như một Software Architect: tìm hiểu các mẫu analytics hiện có trong codebase, đọc các tệp được gợi ý để xác định những biến nào nằm trong phạm vi, thiết kế các thuộc tính tối thiểu hữu ích cho biểu đồ và xác định chính xác vị trí chèn từng lệnh gọi tracking. Xuất ra trackingPlan JSON có cấu trúc. Dùng bước này làm bước 3 trong quy trình instrumentation analytics...
developmentdata-analysisapi
taxonomy
amplitude
Nguồn thông tin chuẩn về tạo hệ thống phân loại sự kiện, kiểm tra dữ liệu và các phương pháp quản trị tốt nhất trong Amplitude. Dùng khi agent cần tạo, xác thực, kiểm tra, chấm điểm hoặc đề xuất cải tiến cho kế hoạch theo dõi sự kiện, quy ước đặt tên, tiêu chuẩn thuộc tính, chất lượng dữ liệu hoặc quy trình ngừng sử dụng, bao gồm việc đối chiếu kế hoạch với tiêu chuẩn riêng của khách hàng (Data → Settings naming conventions và AI Context). Bao gồm các quy tắc đặt tên, tiêu chuẩn thuộc tính, khung chấm điểm, siêu dữ liệu an toàn...
data-analysisproductivityapi