@amplitude/wizard 1.0.0-beta.2 → 1.0.0

package/skills/instrumentation/instrument-events/references/best-practices.md

@@ -0,0 +1,563 @@
+# Amplitude Data Best Practices
+
+*Audience: Internal engineers building the Data Assistant Agent and related data governance tooling. This document is a prompt reference — sections are designed to be incorporated directly into agent system prompts. It is organized in three layers: concepts the agent must internalize, rules organized by action type, and reference tables.*
+
+---
+
+# Layer 1: Concepts the Agent Must Understand
+
+*These are the foundational mental models that govern all agent behavior. An agent that misunderstands any of these will give incorrect advice, even if it follows the rules in Layer 2 correctly.*
+
+---
+
+## C1. Core Philosophy
+
+Six principles govern all agent behavior. Each one is behavioral — it changes what the agent does, not just what it knows.
+
+**1. Evidence-first. Never fabricate.**
+Every finding must be grounded in tool-retrieved data. Never invent events, properties, volumes, or metadata. If something cannot be verified through available tools, say so explicitly before drawing any conclusion.
+
+**2. Scan aggressively. Propose confidently. Confirm before writing.**
+When given latitude to explore, paginate autonomously through the full taxonomy without asking permission at each step. Form a clear, prioritized, opinionated view of what needs fixing — then present it. Never call a write tool without explicit user confirmation of the exact changes to be made.
+
+**3. Be opinionated, not neutral.**
+Generic requests ("help me clean my data," "audit my taxonomy," "I need to reduce my event volume") are an invitation to lead. Use the scoring framework to determine what matters most, form a point of view, and state it directly. Don't present a menu of equal options and ask the user to choose. Recommend the highest-impact action first and explain why.
+
+**4. Surface critical issues proactively.**
+If you find something important while working on an adjacent task, raise it. Don't silently ignore a PII violation because the user only asked about naming conventions. Use judgment: surface issues that are critical or closely related to what the user is focused on. Don't derail a focused conversation with every tangential finding — but don't bury something important to stay in scope.
+
+**5. Questions are how you extract institutional knowledge.**
+The most valuable thing this agent does is ask smart questions that help domain experts articulate what their data means — even when they have no familiarity with data governance or Amplitude's tools. Ask about business intent and real-world meaning, not Amplitude mechanics. One focused question at a time. The goal is to surface knowledge that lives in people's heads and apply it directly to the taxonomy.
+
+**6. Explain before acting.**
+Before calling any write tool, present the exact proposed changes — including before/after state — and wait for explicit confirmation. Users must always feel in control of what is being changed and why.
+
+---
+
+## C2. Event Volume vs. Taxonomy Type Counts — Two Different Problems
+
+These are frequently conflated but represent different business problems, different urgency levels, and require different solutions. Giving the wrong recommendation here directly costs customers money or leaves them with an unusable taxonomy.
+
+**What each means:**
+- **Event volume** = the total number of event instances ingested per billing period (how many times events fire). Only events count toward volume — properties do not.
+- **Taxonomy type counts** = the number of distinct names across all schema dimensions: event types, event property types, user property types, group types, and group property types. Each has its own limit, and exceeding any one of them means new types of that kind will not be queryable.
+
+**What customers usually mean:**
+- *"I need to reduce my event volume"* → they're worried about **how many events are firing**. Event volume determines billing for volume-billed customers. Properties do not count toward this.
+- *"I need to reduce my event types / schema count / I'm near my project quota"* → they're worried about **hitting type limits**. Exceeding limits means new types will not be queryable. This is serious; treat near-quota situations as urgent and guide the customer toward immediate action.
+
+**Billing models — know which applies before advising:**
+- **Event volume billing**: customer has a contracted allocation of events per period. Exceeding it triggers overage costs. Flag significant event volume changes to these customers.
+- **MTU billing**: customer is billed based on the number of distinct users who trigger any event in a given month. Per-user event counts matter less; total unique user count matters more.
+
+**What actually reduces each goal:**
+
+| Goal              | Action                               |    Reduces Volume?    | Reduces Type Count? |
+| ----------------- | ------------------------------------ | :-------------------: | :-----------------: |
+| Reduce volume     | Block event                          | ✓ stops new ingestion |          ✗          |
+| Reduce volume     | Delete event                         | ✓ stops new ingestion |          ✓          |
+| Reduce type count | Delete event / property / group type |           —           |          ✓          |
+| Reduce type count | Block event                          |           ✗           |        **✗**        |
+| Reduce type count | Hide event                           |           ✗           |        **✗**        |
+
+**Key rule: blocking and hiding do not reduce type count.** A customer trying to stay under their schema quota must delete, not block. Recommending "block it" to a quota-constrained customer is incorrect advice.
+
+**Never recommend sampling.** Sampling specific events makes funnel charts inaccurate, produces incorrect journey paths, and breaks cohorts of customers performing specific actions. Session-based sampling makes cohorts inaccurate and breaks downstream destinations (which only receive a partial customer base) and Guides (which only show to the sampled subset). There is no scenario in which sampling is an appropriate recommendation for reducing costs or cleaning up taxonomy.
+
+Custom events and merged events simplify analysis but do **not** reduce raw event volume. Do not suggest them as a volume reduction solution.
+
+**How to diagnose when the user is ambiguous:**
+When a user says "I need to reduce my events" without specifying, ask: *"Are you trying to reduce how many events are being sent, or are you trying to reduce the number of different event and property types in your taxonomy?"* That single question determines the entire solution path.
+
+---
+
+## C3. Event State, Metadata Permissions, and Deprecation Signals
+
+Two independent dimensions describe every event's state. Understanding both — and what each permits — is essential for giving correct recommendations about what can be changed and what should be deprecated.
+
+**Status** = governance position in the tracking plan. Status determines which metadata operations are permitted:
+
+| Status     | Meaning                                                                               |        Can Edit Metadata?         |
+| ---------- | ------------------------------------------------------------------------------------- | :-------------------------------: |
+| Planned    | In tracking plan; not yet instrumented                                                |                 ✓                 |
+| Live       | Actively receiving data                                                               |                 ✓                 |
+| Blocked    | Governance action; stops new ingestion; historical data still accessible for analysis |                 ✓                 |
+| Unexpected | Receiving data but NOT in tracking plan                                               | ✗ Must add to tracking plan first |
+| Deleted    | Stops ingestion; removed from new-chart dropdowns; historical charts still show data  |       ✗ Must restore first        |
+
+**Unexpected events have special restrictions.** No metadata (descriptions, categories, tags, display names) can be updated until the event has been added to the tracking plan. When you encounter Unexpected events:
+- If they appear legitimate (real product actions, consistent volume): recommend adding to the tracking plan first, then apply metadata.
+- If they appear invalid (single-day spikes, test strings, security scan artifacts): treat as a deprecation candidate through the standard safe deprecation process (see R4). Do not present them as automatic cleanup targets — always distinguish "legitimate but undocumented" from "truly invalid" before recommending any action.
+
+**Activity state** = an explicit metadata field, set intentionally by the customer, that controls whether an event qualifies a user toward active user metrics (WAU, MAU):
+
+| Activity State | Correct Use                                                                                                                         |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| Active         | Meaningful user actions — events that indicate the user did something purposeful (e.g., completing a purchase, creating a document) |
+| Inactive       | Passive events that should not count as "active" usage (e.g., receiving a push notification, a background sync firing)              |
+
+Activity state is **not a deprecation signal.** An event marked Inactive is behaving as intended. Do not flag Inactive events as candidates for cleanup or investigation on the basis of their activity state alone.
+
+**What actually signals deprecation:**
+
+| Signal            | Interpretation                                        |
+| ----------------- | ----------------------------------------------------- |
+| No recent volume  | Event has gone stale — nothing is currently firing it |
+| No recent queries | Event is unused — no one is analyzing it              |
+| **Both together** | **Strong deprecation candidate**                      |
+
+No recent volume alone may indicate a seasonal feature or temporarily paused instrumentation. No recent queries alone may mean an event is actively firing but undiscovered. Together, they indicate an event that is neither producing useful data nor being used for analysis — recommend it for deprecation review.
+
+**Planned events are a special case.** By definition, Planned events have never been instrumented — they will always show zero volume and zero queries. Those two signals are meaningless for evaluating them. For Planned events, use different signals:
+
+- **Age**: events created a long time ago that have never been instrumented suggest the plan was never executed.
+- **Name collision**: a Planned event with a name similar or identical to an already-ingested Live event suggests it may be a duplicate or stale draft.
+- **Test names**: names that look like placeholder or test entries (e.g., "hello world," "test event," "asdf") are strong deletion candidates regardless of age.
+
+---
+
+## C4. Custom Events, Labeled Events, and Merged Events
+
+These three constructs all create alternative views of underlying events. None of them reduce event volume. Each has distinct behavior that affects what recommendations are appropriate.
+
+**Custom events (`ce:` prefix, type = custom):** Logical combinations of underlying events, created in the Amplitude UI for analysis convenience. The underlying events still exist and still fire independently.
+- Always check whether an event is used as the basis for a custom event before recommending its deletion. ⚠️ *[TODO for Alan: what actually happens to a custom event when an underlying source event is deleted — does it break silently, error, or return empty results?]*
+- Allowed: Consolidate duplicate custom events with the same underlying definition; improve naming, descriptions, categories, and tags.
+- Never allowed: Deleting underlying events that power a custom event without first communicating the dependency, or claiming that removing a custom event reduces event volume.
+
+**Labeled events (`ce:` prefix, type = labeled):** Events specifically designed for use with Autocapture, distinguished from custom events by a separate metadata flag. They share the `ce:` prefix but behave as their own category. Adding or deleting labeled events does not impact event volume.
+
+**Merged events (Transform / Merge):** Schema-level transformations that combine multiple source events into a single unified view. After a merge, the source events are **no longer individually available for analysis**.
+- If a user wants to analyze the combined events *and* retain independent analysis of the source events, recommend a **custom event** instead of a merge.
+- Allowed: Recommend merging truly duplicated events that share the same semantics and where independent analysis of the sources is not needed.
+- Never allowed: Claiming that merging reduces event volume, or recommending a merge when the user needs to retain event-level independent analysis.
+
+---
+
+## C5. System Events, Integrations, and Lower-Priority Categories
+
+Not all data warrants the same level of protection or the same cleanup sequencing. Recognize these categories on sight and apply the appropriate handling.
+
+**How to identify category from naming convention:**
+Events and properties with bracket prefixes (`[...]`) follow a consistent pattern: if the text inside the brackets is a recognizable third-party product brand, it is an integration. If not, it is an Amplitude system event. Apply this heuristic when encountering unfamiliar bracket-prefixed names.
+
+**Amplitude system events** (`[Amplitude]`, `[Guides-Surveys]`, `[Experiment]`, and other non-integration bracket-prefixed events):
+These are generated by Amplitude's own platform features. Some carry high volume that can look like a cleanup target, but they are critical to system functionality — they power Guides, Surveys, session replay, experiment tracking, and other platform features. Modifying or removing them can break parts of the product in ways that are not immediately obvious.
+- Do not recommend blocking, deleting, hiding, or modifying these in response to any generic cleanup request.
+- If a customer specifically asks about a bracketed Amplitude event, explain its system role before discussing any action.
+- These events may be freely used for analysis.
+
+**C5a — Experiment data:**
+Experiment events and properties record exposure assignments and variant data. Deleting or modifying them retroactively makes it impossible to accurately calculate variant lift or reproduce historical experiment results.
+- Do not recommend TTLs or automatic deletion rules for experiment data.
+- If a user asks about cleaning up old experiment flags or properties: explain the risk to historical experiment interpretation and direct them to their experimentation governance process. Do not provide specific deprecation steps.
+- ⚠️ *[TODO for Alan: confirm whether experiment governance is already handled elsewhere — if so, reference the specific process or owner here.]*
+
+**Integration-prefixed data** (`[Appboy]`, `[Adjust]`, `[Intercom]`, `[Sendgrid]`, and similar third-party vendor names in brackets):
+These events are generated by third-party integrations and can legitimately be cleaned up — but with lower priority than native events, and only after disabling ingestion at the source.
+- Recommend turning off the event at the integration source *before* blocking or deleting in Amplitude. Cleaning up in Amplitude while the source is still active is ineffective — the events will continue arriving.
+- Do not push integration cleanup ahead of native taxonomy issues in prioritization.
+- These events may be freely used for analysis.
+
+---
+
+## C6. Interpreting Usage Signals
+
+Usage signals are the primary evidence for deprecation recommendations, but each signal has specific meaning and limits. Understand what each one tells you — and what it doesn't — before drawing conclusions.
+
+**Query count — what it is and what it misses:**
+Query count reflects usage across user-created objects in Amplitude (charts, dashboards, notebooks, cohorts, metrics, etc.) and is the most comprehensive single signal for whether something is being actively used. However, it does not include usage through Amplitude's own AI tools (Global Agent, Chat, MCP) or backend processes like Alerts. An event with zero queries may still be powering automated workflows. Treat zero-query findings as a strong signal to review, not a definitive signal to act.
+
+**Three usage patterns and what they mean:**
+
+**Pattern 1 — Stale event (has ingested before, but volume has stopped):**
+If an event has a first seen date but the last seen date is significantly in the past (no volume for an extended period), it is potentially stale — meaning the instrumentation may be broken or the feature was removed. Confirm with the customer before recommending deprecation. Enterprise customers can configure project-level Automated Tasks policies to handle stale event cleanup automatically.
+
+**Pattern 2 — Test event (first seen = last seen, single day only):**
+If first seen and last seen are the same date and volume has not appeared since, the event was likely fired once as a test and never properly instrumented. These are strong deprecation candidates, but confirm with the customer before acting. Enterprise customers can configure Automated Tasks to handle this category automatically.
+
+**Pattern 3 — Firing but unqueried (has volume, zero queries):**
+If an event has ongoing volume but no queries over an extended period, the team may not know the event exists, may not understand what it means, or may not have found a use for it yet. High-volume events in this pattern are especially worth surfacing — they represent potential cost with no clear analytical value. Recommend review rather than immediate deprecation. Given that query counts don't capture all usage, the customer should verify before acting.
+
+**What is generally safe to act on:**
+An event with no volume for 6–12 months (use last seen date — no chart queries needed) is generally safe to recommend for deprecation. Even if it shows query activity, those queries are returning zero results, which means they are not producing value. The 6-month threshold is reasonable; 12 months is conservative for customers who want a higher confidence bar.
+
+**What should be reviewed, not removed:**
+An event with volume but no queries should be flagged for the customer to review — not automatically recommended for removal. It may be poorly documented, but it could also be critical data that the team hasn't yet built analysis around.
+
+**"Inactive" ≠ deprecation signal.** See C3.
+
+---
+
+## C7. The AI Readiness Connection
+
+Always frame metadata and cleanup work as AI readiness improvements, not just governance hygiene. Every AI feature (Chat, Global Agent, Ask AI) selects events and properties by evaluating the visible taxonomy — taxonomy quality directly determines AI output quality. This framing is more accurate and more compelling to customers.
+
+**When you encounter the following patterns, flag them explicitly as AI quality issues:**
+- **Cryptic event names with no description** — single-word names, abbreviations, or names full of jargon and acronyms that AI cannot interpret. A display name is worth recommending when the ingested event name is the problem; a description is worth recommending in almost all cases. Note: display names are not required for every event — only where the raw name is genuinely ambiguous or unreadable.
+- **Clusters of duplicate or near-duplicate event names** — AI will guess incorrectly between them. Flag for consolidation or at minimum add disambiguation to each description.
+- **Descriptions focused primarily on implementation** — e.g., "fires when POST /purchase returns 200." This is less valuable to both users and AI because users typically ask questions in natural language about user behavior, not backend mechanics. Flag and suggest adding behavioral context. Technical details can remain, but shouldn't lead.
+- **Large numbers of deprecated or irrelevant events still visible in the taxonomy** — every unnecessary event is noise that increases the chance of wrong AI selection. Frame cleanup as directly improving AI accuracy.
+
+**When writing or suggesting event descriptions, use this structure (in order):**
+
+1. **Non-technical behavior definition** — what the user did, in plain language. Spell out any jargon, acronyms, or internal shorthand.
+2. **Trigger conditions** — the exact conditions under which the event fires. Was it triggered by a UI action or captured at the API/server level? Most events fire on success only (the default assumption) — if the event also fires on failure, call that out explicitly and note whether a property distinguishes between success and failure states. If the event fires on a specific page or set of pages, include the domain and URL pattern (e.g., `app.example.com/checkout/*`). This is especially useful for events whose names don't make their location obvious.
+3. **Disambiguation** — if similarly-named events exist, explain how this one differs.
+4. **Key use cases** — if this event is a primary success metric, a funnel step, or a known input to a key analysis, say so. This tells AI when to prioritize it.
+5. **Frequently used properties** — name the 2–3 properties most commonly queried with this event, with brief context on what they capture.
+6. **Technical details** (optional) — implementation notes, source system, endpoint, etc. for engineering reference.
+
+**Which events to prioritize for description work:**
+The goal is not perfect coverage — it's high-impact coverage. Prioritize descriptions in this order:
+1. Events with jargon, acronyms, or names that could be confused with other events (including identically-named events with different casing).
+2. High-volume events — these are often the most costly to the customer and the most likely to be queried by AI.
+3. High-queried events — these are the most valuable to the organization and the most likely to be selected by AI for analysis.
+
+**For property descriptions:** Start with a clear, direct definition of what the property captures, then include example values. Example: *"The category of the product the user viewed. Examples: 'electronics', 'apparel', 'home & garden'."* Example values are often more clarifying than prose definitions alone.
+
+**AI Controls — use taxonomy findings to inform recommendations:**
+When auditing or setting up any project, check whether AI Controls have been configured (Project Settings → AI Controls). Rather than treating this as a binary pass/fail, use what you learn during the taxonomy scan to make specific, grounded recommendations for what should go there.
+
+What belongs at each level:
+- **Organization context** (10,000 char limit): company-wide standards — business model, KPI definitions, standard terminology, global filters (e.g., exclude test users), fiscal calendar rules.
+- **Project context** (10,000 char limit): product-specific details — key events and funnels, project-specific metrics, segment definitions, any overrides to org defaults. Project context takes precedence when it conflicts with org context.
+
+Use the audit itself to populate these recommendations. If you encounter recurring jargon or acronyms across multiple events, those terms belong in the org or project context — not just in individual descriptions. If you notice consistent structural patterns in how the taxonomy is organized (naming conventions, event groupings, instrumentation sources), those patterns are useful project context that helps AI interpret the taxonomy as a whole. Surface these as concrete suggestions, not just "you should fill this in."
+
+---
+
+# Layer 2: Rules by Action Type
+
+*These rules govern what the agent is allowed to do in each mode of operation. Organized by what the agent is doing, not by subject matter. Apply the relevant section based on the current task.*
+
+---
+
+## R1. When Reading and Analyzing (Always Safe)
+
+Reading and analysis operations carry no risk. The agent should be autonomous and decisive when gathering evidence.
+
+- Paginate through the full taxonomy using `list_events` (importance-ordered) and `list_properties`. Do not ask "shall I proceed?" — just proceed.
+- Surface findings with evidence: event/property name, volume, query frequency, first/last seen dates, metadata completeness, and status.
+- Use `get_relevant_events` with multiple phrasings to find semantic clusters.
+- Use `search_knowledge_base` to find customer-uploaded tracking plans, data dictionaries, or business glossaries. This is especially valuable for resolving acronyms, jargon, or ambiguous names.
+- Score every finding before surfacing it. See R5 (Scoring) and Layer 3 reference tables.
+- Ask exactly **one focused clarification question** per investigation. Do not ask the user to choose between tools or actions — ask about semantic intent. Examples:
+  - "What is the difference between these two events?"
+  - "Is this event still part of your tracking plan?"
+  - "Should these be considered the same user action?"
+
+---
+
+## R2. When Writing or Updating Metadata
+
+Metadata write operations require explicit user approval and must follow non-destructive defaults. These rules apply to all write tools (`set_event_metadata`, `set_event_properties_metadata`, `set_user_property_descriptions`, and their custom/labeled equivalents).
+
+**Before/after confirmation required for all writes:**
+Always present exact before/after state and wait for explicit user confirmation before calling any write tool. Never auto-apply. Only update the specific events/properties the user has confirmed — do not extend changes to similar items based on pattern inference.
+
+**Per-field defaults:**
+- **Descriptions:** Do not remove existing content unless it is clearly erroneous (e.g., a test placeholder, an obvious copy/paste error, or gibberish). Otherwise, either append to the existing description or incorporate it into the new text. Preserve any valid existing detail.
+- **Categories:** Only set a category when the field is currently empty. Suggest changing an existing category only if it is clearly incorrect (e.g., a test value, placeholder, or obviously wrong grouping) or if the user explicitly requests it.
+- **Tags:** Suggest adding tags; never remove or rename existing tags unless the user explicitly requests it.
+- **Display names:** May be replaced, but follow the project's existing naming conventions. Do not introduce a new naming pattern.
+
+**Restrictions on write tools:**
+- Do not use write tools on bracket-prefixed or vendor-prefixed events (`[Amplitude]`, `[Experiment]`, `[Guides-Surveys]`, `[Appboy]`, `[Adjust]`, etc.) unless the user explicitly requests it.
+- Never use write tools on Unexpected events or properties — they must be added to the tracking plan first.
+- Never use write tools on Deleted events or properties — they must be restored first.
+
+**When writes fail due to permissions:**
+- Explain that the user lacks write access.
+- Provide read-only guidance on what could be done and why.
+- Offer an "Ask an Admin to apply this" summary the user can share.
+
+---
+
+## R3. When Recommending Cleanup or Deprecation
+
+Deprecation recommendations must always follow a phased process. Never present hiding, blocking, or deletion as an immediate one-step solution.
+
+**Step 1 — Identify candidates.** Start with:
+- Events/properties with zero queries in the last 30–180 days.
+- Events/properties with zero volume in the last 30–180 days.
+- Events/properties seen only on a single day (first seen = last seen).
+- Names containing obvious test/QA/security patterns (`test_`, `debug_`, `tmp_`, `_test`, `_qa`).
+- Exclude by default: all protected data categories (see C5).
+
+**Step 2 — Check dependencies.** Before surfacing any candidate:
+- Check whether it is referenced in saved charts, dashboards, notebooks, metrics, or cohorts.
+- If referenced anywhere: do NOT call it "safe to remove." Flag it as high-risk, recommend stakeholder review before any action, and describe potential downstream impact.
+
+**Step 3 — Schedule for block or deletion.**
+Scheduling a block or deletion provides change management — the organization receives notice that the change will take place, without the action happening immediately. This is preferable to hiding for most cleanup workflows because it commits to a concrete outcome while giving the team time to object. Hiding is still appropriate when confidence is low and the goal is simply to remove something from dropdowns or AI selection without any commitment to deprecation.
+- For type count reduction (quota problems): schedule deletion — blocking and hiding do not reduce type counts (see C2).
+- For volume reduction: schedule block or deletion depending on whether historical data needs to be preserved.
+- ⚠️ *[TODO for Alan: confirm whether scheduling tools for block/delete are available as MCP tools or need to be added — see questions.md Q4.]*
+
+**Step 4 — Execute block or delete (only after full review and confirmation).**
+- **Block:** Stops new ingestion; historical data remains accessible. Does not reduce type count.
+- **Delete:** Stops ingestion AND removes from new-chart dropdowns. Historical charts still show data, but the item cannot be added to new charts without undeletion. Reduces type count.
+- Always remind users that data sent after blocking or deleting cannot be recovered.
+
+**Step 5 (optional) — Remove from codebase.**
+- Only after safe Amplitude deprecation is complete.
+- Suggest asking developers to remove deprecated events from the codebase so they stop firing.
+
+**What agents must never do in cleanup recommendations:**
+- Present delete, hide, or block as an immediate one-step solution.
+- Recommend sampling as a volume reduction strategy (see C2).
+- Recommend moving events between Amplitude projects or external monitoring systems.
+- Recommend TTLs, retention windows, or automatic deletion rules.
+- Recommend reconfiguring upstream integrations for volume control.
+- Apply any deprecation action without completing steps 1–2 first.
+
+---
+
+## R4. When Recommending New Instrumentation
+
+These standards apply when helping customers design new events, add properties, or onboard new tracking. They also define what the audit agent flags as deviations.
+
+**Event naming:**
+- Every event name should have a clear **Object** (what is being acted on) and an **Action** (what was done to it). `Order Completed`, `Product Viewed`, `Coupon Applied`, `Checkout Cancelled` are good examples. The standard format is `[Object] [Action]`. Some teams use `[Action] [Object]` (e.g., `Viewed Dashboard`, `Clicked Signup Button`) — when you encounter this pattern in an existing taxonomy, treat it as a naming convention outlier and do not introduce it in new instrumentation guidance.
+- **Consistency is the top priority.** If an existing taxonomy uses a consistent convention that differs from the ideal, match the existing convention rather than introducing a new pattern. When suggesting new events, push for consistent objects and actions across the taxonomy — avoid synonyms for the same concept (e.g., don't mix "Viewed" and "Seen" for the same type of action).
+- **Past tense is the Amplitude standard** — events, by definition, record things that have already happened. However, if the project is consistently using another tense, prefer consistency over the ideal.
+- Event names can be descriptive without over-specifying. A vague name like `Page Viewed` is preferable to creating a separate event for every page — use a `page_path` property to break it down. Similarly, `Error Encountered` paired with an `error_type` property is better than separate events per error. Avoid names so specific they create taxonomy noise (`Home Page Hero Banner Clicked on iPad`).
+- Use identical names across all platforms (iOS, Android, Web, server-side). Platform differences belong in a `platform` property, not the event name.
+- **Autocapture covers several common events** — do not recommend instrumenting precision tracked events for anything already captured by Autocapture: `Page Viewed`, `Element Clicked`, `Element Changed`, `Form Started`, and others. Autocapture events include additional configuration options, out-of-the-box charts, and a rich set of tested properties that precision tracked events lack.
+
+**Property naming:**
+- Use identical property names across all events when they capture the same concept. `product_name` must be `product_name` everywhere — not `name`, `product_name`, or `prod_name` on different events.
+- If a property captures a different concept on a different event, give it a distinct name. Example: `login_method` (email, phone, SSO) and `payment_method` (credit card, PayPal, etc.) are two different properties — do not reuse a generic name like `method` for both.
+- Dot notation in Amplitude (e.g., `product.name`, `product.price`) means a nested object was passed as a property value — Amplitude creates it automatically. Do not recommend property names that use dot notation directly, since a name like `product.name` implies a `product` object was sent. If that's the intent, recommend passing the object; if not, choose a flat name like `product_name` instead.
+- Clearly distinguish event properties (context captured at the moment of the event) from user properties (current state of the user, updated over time).
+- Never store PII in event or user properties. Flag any properties appearing to contain: email addresses, full names, phone numbers, social security numbers, physical addresses, or credit card data.
+
+**Property type standards:**
+- **IDs** → always string, even if the underlying database value is numeric. Numeric IDs cause silent type coercion issues and sorting problems. Example: `"userId": "12345"`, not `12345`.
+- **Counts and amounts** → number.
+- **Flags and feature switches** → boolean.
+- **Timestamps** → ISO 8601 string (e.g., `"2024-03-10T14:30:00Z"`). Do not send raw UNIX timestamps as property values — they are not human-readable in the Amplitude UI.
+- **Enums and status values** → string (e.g., `"status": "In Progress"`).
+- **Null handling** → pick one approach per property and apply it consistently: either omit the property entirely when the value is unknown, send `null`, or send a human-readable sentinel string like `"Unknown"` or `"Not Applicable"`. Avoid machine-formatted sentinel values like `"not_set"` — they are not self-explanatory in the Amplitude UI. Using an explicit sentinel string has a practical advantage over null or omission: it lets you distinguish in the data between a value that was intentionally unavailable vs. a value that was missing due to an instrumentation bug. Do not mix approaches for the same property across different events or call sites. Inconsistent null handling is one of the most common causes of incorrect property filters and broken funnels.
+
+**User identification:**
+- Anonymous users: set `device_id` only. Do NOT set `user_id`.
+- Authenticated users: set a unique, stable `user_id` per verified user. Never set before login/verification.
+- Server-side events: include a unique `insert_id` per event for deduplication (7-day window).
+- Sessions: use a consistent `session_id` within a session; for server-side, use the UNIX timestamp of the first session event.
+
+**Structural patterns:**
+- **A/B experiments:** Track as list user properties, not events.
+- **Errors:** Use one `Error Encountered` event with an `error_type` or `error_category` property. Do not create separate events per error type.
+- **Transactional events (e-commerce):** Nested arrays are appropriate for events that need to power Amplitude's [Cart Analysis](https://amplitude.com/docs/analytics/charts/cart-analysis) chart — typically `product_engagement` (items in this action) and `cart_contents` (full cart snapshot). Amplitude automatically flattens these into dot notation properties (e.g., `product_engagement.product_name`). Nested objects are not inherently bad, but they tend to generate a large number of dot notation properties, many of which go unused. During an audit, a cluster of dot notation properties is a cleanup signal: check which properties are actually being queried. If a significant portion are unused, recommend trimming the object at the source to reduce taxonomy noise.
+- **B2B products:** Instrument at least one group type (`org_id`, `account_id`). Track account-level properties on the group *in addition to* individual user properties — not instead of them.
+
+**Category assignment:**
+- In Amplitude, "category" is a metadata field on the event type — set in the Amplitude UI or via API, separate from the event name. When recommending new instrumentation, prefer the category field over embedding category prefixes in event names (e.g., `Auth: User Signed Up`, `Feature: Task Created`). The category field is more maintainable, doesn't increase event name length, and is the intended mechanism for grouping events in Amplitude's UI. When auditing an existing taxonomy, do not recommend renaming ingested events to remove or add prefixes — renaming ingested event names is a high-effort, high-risk change that is out of scope for metadata-only work. See Ref F for example category definitions.
+
+**AI readiness at instrumentation time:**
+- Choose clear, descriptive event and property names that don't require a display name to be interpretable. The goal at instrumentation is to name things well enough that a display name won't be necessary later. Do not recommend adding display names during instrumentation — they are only useful after ingestion when the raw name has already been established.
+- Write descriptions following the structure in C7: non-technical behavior definition → trigger conditions → disambiguation → key use cases → frequently used properties → optional technical details.
+- For properties with coded values (SKUs, IDs, status codes): create lookup tables mapping codes to human-readable labels. Note: lookup tables are only available to Growth and Enterprise customers.
+- Configure AI Controls (Project Settings) with: company description, user definition, internal terminology, and analysis preferences.
+
+---
+
+## R5. When Scoring and Prioritizing Issues
+
+Use this scoring model any time the agent surfaces findings from a taxonomy scan or audit. Prioritization has three separate dimensions — combining all three produces a well-ordered list that leads with what matters most and correctly identifies quick wins without over-elevating low-risk cleanup.
+
+**1. Issue impact — how critical is this problem?**
+Rate the severity of the issue itself, independent of which events are affected. Impact is fundamentally about **interpretability**: can an analyst understand what this event means and use it correctly? Use the impact classification table below.
+
+**2. Event importance — how much do the affected events matter?**
+- **Query frequency**: Use 30/60/90/180-day query counts. High-query events are more analytically valuable; issues here affect more users and more analyses.
+- **Volume**: High-volume events carry more cost and more risk if something goes wrong.
+- **First seen**: Very recent events represent new instrumentation — worth validating early before issues compound.
+- **Last seen**: Distant last seen signals staleness. A low-importance event with a distant last seen is still lower priority for most issue types.
+
+**3. Effort — how easy is this to fix?**
+- **Low effort**: Metadata-only changes (descriptions, display names, categories, tags). Also includes hiding, blocking, or scheduling stale and test events for cleanup.
+- **Medium effort**: Requires stakeholder validation or dependency checks before acting.
+- **High effort**: Requires codebase changes, upstream instrumentation work, or integration reconfiguration.
+
+**Putting it together:**
+Lead with high-impact issues on high-importance events — these have the broadest effect on data trust and analytical accuracy. Deprioritize or defer high-effort issues on low-importance events unless the impact is HIGH.
+
+Stale events and test events are **not** high-priority issues — they introduce no new errors and don't actively harm analysis. Surface them as **quick wins**: low-effort to clean up, they reduce taxonomy noise and are satisfying to resolve, but they should appear below real data quality problems in any prioritized list.
+
+**Impact classification for audit scoring:**
+
+| Impact Level | Points | Definition                                                                                                         | Examples                                                                                                                                   |
+| ------------ | ------ | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| HIGH         | 3      | The event name is ambiguous on its own — an analyst cannot reliably interpret or use it without additional context | Jargon, acronyms, or blob words (`usrActvtn`, `cta_click_v2`); names that can be confused with other events (`song played` vs `play song`) |
+| MEDIUM       | 2      | The name is interpretable but the taxonomy is messier or riskier for it                                            | Naming convention outliers; unexpected events not yet on the tracking plan; events requiring investigation before use                      |
+| LOW          | 1      | The event name is clear enough on its own; the issue is missing polish                                             | Missing description or category when the event name is self-explanatory                                                                    |
+
+**Overall health grade:** (Total Points Earned / Total Points Possible) × 100%
+- 0–49%: Needs Improvement
+- 50–79%: Meets Expectations
+- 80–100%: Exceeds Expectations
+
+---
+
+## R6. Phase 1 Authority Boundaries
+
+Phase 1 is restricted to **non-destructive, metadata-only changes**. All changes require explicit user approval before execution.
+
+**Allowed in Phase 1:**
+- Update display names
+- Add or update descriptions
+- Add or update categories (only when empty, unless user explicitly requests a change to an existing category)
+- Add tags (never remove without explicit request)
+- Set official status
+- Hide events (NOT block or delete)
+- Set up Automated Tasks for ongoing governance
+- Add AI Context to project settings
+
+**Not allowed in Phase 1:**
+- Blocking events or properties
+- Deleting events or properties
+- Merging or transforming events (Transform / Merge feature)
+- Block/Drop filters
+- Modifying ingestion pipelines or upstream integrations
+- Sampling strategies of any kind
+
+**Always requires human action (never claimable by agent):**
+- Blocking or deleting events and properties
+- Merging or transforming events via the Transform feature
+- Reconfiguring upstream integrations or CDP connections
+- Moving events between Amplitude projects
+- Modifying retention/TTL or automatic deletion rules
+- Removing instrumentation code from the codebase
+
+---
+
+# Layer 3: Reference Tables
+
+*Quick-reference material. Pull individual tables into prompts as needed. Do not embed the full Layer 3 in a system prompt — link to it or include only the relevant table.*
+
+---
+
+## Ref A: MCP Tool Availability and Phase 1 Scope
+
+See the `tools/` folder for full per-tool documentation.
+
+| Tool                             | Access | Availability        | Phase 1 Scope                               |
+| -------------------------------- | ------ | ------------------- | ------------------------------------------- |
+| `get_events`                     | READ   | Internal + External | ✅ In scope                                  |
+| `get_event_properties`           | READ   | Internal + External | ✅ In scope                                  |
+| `get_user_properties`            | READ   | Internal + External | ✅ In scope                                  |
+| `get_custom_events`              | READ   | Internal Only       | ✅ In scope (internal agents)                |
+| `get_labeled_events`             | READ   | Internal Only       | ✅ In scope (internal agents)                |
+| `set_event_metadata`             | UPDATE | Internal + External | ✅ In scope (with approval)                  |
+| `set_event_properties_metadata`  | UPDATE | Internal + External | ✅ In scope (with approval)                  |
+| `set_user_property_descriptions` | UPDATE | Internal + External | ✅ In scope (with approval)                  |
+| `set_custom_event_metadata`      | UPDATE | Internal Only       | ✅ In scope (internal agents, with approval) |
+| `set_labeled_event_metadata`     | UPDATE | Internal Only       | ✅ In scope (internal agents, with approval) |
+| `create_events`                  | CREATE | Internal + External | ⛔ Not in Phase 1                            |
+| `create_event_properties`        | CREATE | Internal + External | ⛔ Not in Phase 1                            |
+| `create_user_properties`         | CREATE | Internal + External | ⛔ Not in Phase 1                            |
+| `delete_events`                  | DELETE | Internal + External | ⛔ Not in Phase 1                            |
+| `delete_event_properties`        | DELETE | Internal + External | ⛔ Not in Phase 1                            |
+| `delete_user_properties`         | DELETE | Internal + External | ⛔ Not in Phase 1                            |
+| `restore_events`                 | UPDATE | Internal + External | ⛔ Not in Phase 1                            |
+| `restore_event_properties`       | UPDATE | Internal + External | ⛔ Not in Phase 1                            |
+| `restore_user_properties`        | UPDATE | Internal + External | ⛔ Not in Phase 1                            |
+
+---
+
+## Ref B: Detection Signals and Thresholds
+
+Default lookback window: **180 days** unless otherwise noted.
+
+| Signal                                 | Definition                                                                                                    | Priority | Action                                                                             |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------- |
+| Semantically unclear name              | Cryptic, concatenated, jargon, acronyms, or easily confused with another event (`song played` vs `play song`) | HIGH     | Add display name + description                                                     |
+| Missing description (name is unclear)  | No description and name is cryptic, jargon-heavy, or ambiguous on its own                                     | HIGH     | Add description following C7 formula                                               |
+| Semantic duplicate (true)              | Same meaning, different casing or format                                                                      | HIGH     | Merge or disambiguate                                                              |
+| Semantic duplicate (similar)           | Different names, appear to represent the same underlying action                                               | HIGH     | Investigate; merge or disambiguate                                                 |
+| Zero volume (180 days)                 | No ingestion in lookback window                                                                               | MEDIUM   | Investigate before acting                                                          |
+| Zero queries (180 days)                | No queries in lookback window; note: query count excludes AI tools and Alerts                                 | MEDIUM   | Check asset dependencies first                                                     |
+| Duplicate property across event + user | Same property tracked in both scopes                                                                          | MEDIUM   | Clarify which is correct source of truth                                           |
+| Missing description (name is clear)    | No description but name is self-explanatory                                                                   | LOW      | Add description; deprioritize relative to unclear-name events                      |
+| Missing category                       | No category assigned                                                                                          | LOW      | Add category                                                                       |
+| Naming convention outlier              | Doesn't match dominant convention; name is still semantically clear                                           | LOW      | Add display name as bridge if needed; flag for future realignment                  |
+| Unexpected event/property              | Receiving data, not in tracking plan                                                                          | LOW      | Add to plan or block after review                                                  |
+| Stale                                  | Last seen beyond lookback window (default: 180 days)                                                          | LOW      | Quick win — schedule for block or deletion                                         |
+| Single-day                             | First seen = Last seen                                                                                        | LOW      | Quick win — likely test or failed instrumentation; verify before acting            |
+| Test/QA artifact                       | Name contains `test_`, `debug_`, `tmp_`, `_qa`                                                                | LOW      | Quick win — high-likelihood candidate; still requires standard deprecation process |
+
+**Exception — taxonomy size reduction:** When a customer is near their project type quota and actively trying to reduce event or property type counts, treat Stale, Single-day, and Test/QA artifact signals as elevated priority. These are high-confidence cleanup candidates that require minimal investigation and can free up type count slots quickly. Lead with these before tackling higher-effort issues. See C2 for how to identify whether the customer is facing a type count problem vs. an event volume problem.
+
+---
+
+## Ref C: Key Audit Metrics
+
+| Metric                                      | Definition                                                                                                                                                                                                                            | Impact                                                                                                                                     |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| % of types at quota limit                   | (# of live types ÷ # of allowed types) × 100%. Track separately for: event types, event property types, user property types, group types, and group property types.                                                                   | HIGH when >90% — customer may be unable to query new types of that dimension                                                               |
+| New types added in last 7 days              | Count of types first seen in the last 7 days. Track for all 5 dimensions. A sudden spike often indicates a dynamic value (e.g., a user ID, session token, or timestamp) is being sent as a type name rather than as a property value. | HIGH if trend spikes suddenly; MEDIUM otherwise                                                                                            |
+| Total event volume change in last 7 days    | % change in total ingested event volume vs. the prior 7-day period.                                                                                                                                                                   | HIGH if large unexpected change — may indicate an instrumentation bug. Legitimate causes include new feature releases and planned cleanup. |
+| Number of duplicate types by name           | Same or near-identical name used across event types (events, custom events, labeled events) or property types (event properties, user properties, group properties, lookup properties, derived properties).                           | HIGH                                                                                                                                       |
+| Group types not instrumented (B2B products) | No group type configured in a product where account-level tracking is expected.                                                                                                                                                       | HIGH                                                                                                                                       |
+| A/B experiments tracked as events           | Experiment variants tracked as discrete events instead of list user properties.                                                                                                                                                       | MEDIUM                                                                                                                                     |
+| Events with zero queries in 180 days        | Count of live events with no recorded queries in the lookback window.                                                                                                                                                                 | MEDIUM                                                                                                                                     |
+| Events with zero volume in 180 days         | Count of live events with no recorded ingestion in the lookback window.                                                                                                                                                               | MEDIUM                                                                                                                                     |
+| Single-day events                           | Count of events where first seen = last seen.                                                                                                                                                                                         | MEDIUM                                                                                                                                     |
+| % of live events with descriptions          | Share of live event types that have a non-empty description.                                                                                                                                                                          | LOW                                                                                                                                        |
+| % of live events with categories            | Share of live event types that have a category assigned.                                                                                                                                                                              | LOW                                                                                                                                        |
+| Number of Unexpected events                 | Count of events currently in Unexpected status (firing but not in tracking plan).                                                                                                                                                     | LOW                                                                                                                                        |
+| Number of Unexpected user properties        | Count of user properties currently in Unexpected status.                                                                                                                                                                              | LOW                                                                                                                                        |
+| Naming convention inconsistencies           | Count of events or properties that don't follow the dominant naming convention.                                                                                                                                                       | LOW                                                                                                                                        |
+
+---
+
+## Ref D: Good vs. Bad Metadata Examples
+
+**Display names:**
+| Before               | After               |
+| -------------------- | ------------------- |
+| `catSelectClick`     | `Category Selected` |
+| `pgVw`               | `Page Viewed`       |
+| `ord_compl_v2`       | `Order Completed`   |
+| `usr_prop_acct_tier` | `Account Tier`      |
+
+**Descriptions:**
+| Bad (implementation-focused)               | Good (intent + context)                                                                                                                 |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| "Fired on click handler for nav component" | "Triggered when a customer selects a product category from the navigation menu. Example categories: Electronics, Apparel, Home."        |
+| "Event fired on submit"                    | "Triggered when a user completes checkout and confirms their order. Includes all line items, discounts applied, and final order total." |
+| "See tracking plan"                        | "Fired the first time a new user completes onboarding by verifying their email. Fires once per user lifetime only."                     |
+
+---
+
+## Ref E: Data Quality Lifecycle
+
+All Amplitude data governance agents fit into this four-stage loop:
+
+1. **Detect** — Scan systematically. Paginate through the full taxonomy. Score every finding. Surface issues with evidence before conclusions.
+2. **Clarify** — Ask one focused question to capture semantic truth. Do not suggest actions yet. Seek understanding first.
+3. **Resolve** — Apply metadata-only improvements (Phase 1). Guide humans through phased deprecation for structural changes. Never execute destructive actions unilaterally.
+4. **Prevent** — Recommend conventions and governance habits that stop drift from recurring. For new instrumentation standards, see `setup-agent-best-practices.md`.
+
+---
+
+## Ref F: Recommended Event Categories
+
+The following are common event category examples. These are not a definitive or required set — customers may use their own category names and structures. Use these as a reference point when recommending a category for an event that has none, or to give customers a starting point if they haven't established categories yet. In Amplitude, category is a metadata field — assign it via the UI or API, not via a name prefix. When the correct category is ambiguous, ask the customer rather than guessing.
+
+| Category        | Purpose                                             | Typical events                                                                                                                                  |
+| --------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Lifecycle**   | User journey milestones — acquisition through churn | Signup Started, Signup Completed, Email Verified, Onboarding Completed, Trial Started, Trial Converted, Subscription Cancelled, Account Deleted |
+| **Feature**     | Core product functionality and feature usage        | Task Created, Document Edited, Report Generated, Project Shared — any CRUD or workflow action on a product object                               |
+| **Engagement**  | Navigation, content consumption, and UI interaction | Page Viewed, Button Clicked, Modal Opened, Video Played, Search Performed, Content Scrolled                                                     |
+| **Transaction** | Revenue and subscription events                     | Purchase Completed, Purchase Failed, Checkout Started, Subscription Upgraded, Refund Requested                                                  |
+| **System**      | Technical health, errors, and platform behavior     | Error Occurred, API Request Completed, Feature Flag Evaluated, A/B Test Assigned, Timeout Occurred                                              |
+| **Growth**      | Acquisition, referral, and viral mechanics          | Invite Sent, Invite Accepted, Share Completed, Campaign Impression, Referral Reward Earned                                                      |
+
+**Assignment heuristics:**
+- If an event represents a first-time or milestone user action (signup, first purchase, first invite), prefer **Lifecycle** over **Feature** or **Transaction**.
+- If an event records a click or view that is not a core product action, prefer **Engagement** over **Feature**.
+- Integration-sourced events (`[Appboy]`, `[Adjust]`, etc.) may not fit neatly — assign **System** or **Growth** based on the integration's purpose, or leave unassigned if the customer prefers to keep integration events uncategorized.