@amplitude/wizard 1.0.0-beta.2 → 1.0.0

package/skills/instrumentation/add-analytics-instrumentation/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: add-analytics-instrumentation
+description: >
+  End-to-end analytics instrumentation workflow for a PR, branch, file,
+  directory, or feature. Reads the code, discovers what events should be
+  tracked, and produces a concrete instrumentation plan — all in one shot. Use
+  this skill whenever a user wants to add analytics to a PR, asks "instrument
+  this PR", "add tracking to this branch", "what analytics does this file need",
+  "instrument the checkout flow", "run the full instrumentation workflow", or any
+  request that implies going from code changes to a tracking plan. Also trigger
+  when the user gives you a PR link, branch name, file path, or feature
+  description and mentions analytics, events, or instrumentation. This is the
+  main entry point for the analytics workflow — prefer it over calling the
+  individual steps (diff-intake, discover-event-surfaces, instrument-events)
+  separately.
+---
+
+# add-analytics-instrumentation
+
+You are the orchestrator for the analytics instrumentation pipeline. Your job is
+to figure out what the user wants to instrument, gather the relevant code, and
+run the pipeline to produce a tracking plan.
+
+## Pipeline
+
+### Step 0: Capture intent
+
+Before running anything, determine **what** the user wants to instrument. There
+are four input types — infer the type from what the user has already provided in
+the conversation. Only ask if it's genuinely ambiguous.
+
+| Input type           | How to recognize it                                                            | Example                                                                     |
+| -------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
+| **PR**               | A PR URL, PR number, or phrases like "this PR", "my PR"                        | `instrument PR #42`, `https://github.com/org/repo/pull/42`                  |
+| **Branch**           | A branch name or "this branch", "my branch", "current branch"                  | `instrument feature/checkout`, `add tracking to this branch`                |
+| **File / Directory** | A file path, directory path, or glob pattern                                   | `instrument src/components/Checkout.tsx`, `add analytics to src/payments/`  |
+| **Feature**          | A natural-language description of functionality, not a specific code reference | `instrument the onboarding flow`, `add tracking to the checkout experience` |
+
+**Inference rules:**
+- If the user provided a URL or `#number` → **PR**
+- If the user provided something that looks like a branch name (contains `/`, no file extension, matches a git branch) → **Branch**
+- If the user provided a path that exists on disk (file or directory) → **File / Directory**
+- If none of the above match and the input is descriptive → **Feature**
+- If the conversation already contains a PR link, branch name, or file path from earlier messages, use that instead of asking again
+
+**If ambiguous**, ask the user:
+
+> What would you like to instrument?
+> 1. A specific file or directory
+> 2. A PR
+> 3. A branch
+> 4. A feature (describe it and I'll find the relevant code)
+
+Once you know the input type, proceed to the appropriate step:
+
+- **PR or Branch** → go to Step 1 (diff-intake)
+- **File / Directory** → go to Step 1a (direct file read)
+- **Feature** → go to Step 1b (feature search)
+
+### Step 1: diff-intake skill (PR or Branch)
+
+Invoke the `diff-intake` skill with the user's PR or branch reference.
+
+It produces a `change_brief` YAML block.
+
+Capture the full YAML output — step 2 consumes it verbatim. Skip to Step 2.
+
+### Step 1a: Direct file read (File / Directory)
+
+Skip diff-intake entirely — there's no diff to analyze. Instead, build the
+`change_brief` YAML yourself by reading the files directly.
+
+1. **Resolve the input.** If a directory, find all source files in it (skip
+   tests, config, lock files, generated code). If a single file, just use that.
+2. **Read each file** and summarize what it does — focus on user-facing behavior,
+   not implementation details.
+3. **Scan for existing instrumentation** using the same patterns as diff-intake:
+   `track(`, `trackEvent(`, `logEvent(`, `amplitude.track(`, `ampli.`, and
+   analytics-related imports.
+4. **Build the `change_brief` YAML** with `analytics_scope: high` (the user
+   explicitly asked to instrument these files, so assume they want tracking).
+   Set `primary: feat` and `classification.types: [feat]`. Populate
+   `file_summary_map` with each file's summary, layer, and existing
+   instrumentation.
+
+Proceed to Step 2 with the YAML you built.
+
+### Step 1b: Feature search (Feature)
+
+The user described a feature in natural language. Your job is to find the
+relevant code, then build a `change_brief`.
+
+1. **Search git commit history** to find related commits. Use `git log --all --grep="<patterns>"`. This will find relevant commits. Then read the git commit body to understand the feature and relevant files. If the results are good, then proceed to generating the `change_brief` YAML
+2. **Search the codebase** for files related to the described feature. Use a
+   combination of:
+   - Grep for keywords from the feature description (component names, route
+     paths, function names, domain terms)
+   - Glob for likely file paths (e.g., `**/checkout/**`, `**/onboarding/**`)
+   - Read route definitions, navigation configs, or index files to find entry
+     points
+3. Build the `change_brief` YAML.
+
+Proceed to Step 2 with the YAML you built.
+
+### Step 2: discover-event-surfaces
+
+Invoke the `discover-event-surfaces` skill, passing the `change_brief` YAML
+from step 1.
+
+It produces an `event_candidates` YAML block. If there are zero candidates,
+stop and tell the user the change has user-facing impact but no events worth
+instrumenting were identified.
+
+If event_candidates is empty, stop here and tell the user there's nothing to
+instrument.
+
+Capture the full YAML output — step 3 consumes it.
+
+### Step 3: instrument-events
+
+Invoke the `instrument-events` skill, passing the `event_candidates` YAML from
+step 2.
+
+It produces a `trackingPlan` JSON with exact file locations, tracking code, and
+property definitions for every critical (priority 3) event.
+
+## Presenting the result
+
+After step 3 completes, present the tracking plan to the user. Walk through each
+event briefly:
+
+- What it tracks and why it matters
+- Where the tracking call goes (file + function)
+- What properties it sends
+
+Then ask if they want to adjust anything or proceed to implementation.
+
+## Error handling
+
+If any step fails (e.g., the PR doesn't exist, git commands error, no files to
+analyze), surface the error clearly and stop. Don't try to continue with
+incomplete data.

package/skills/instrumentation/diff-intake/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: diff-intake
+description: >
+  Reads a PR or branch diff and produces a structured YAML change brief for
+  downstream analytics instrumentation skills. Use this as the first step
+  whenever a user shares a PR link, branch comparison, or raw diff and wants
+  to understand what changed, what needs tracking, or how to instrument a
+  feature. Trigger on phrases like "review this PR", "what changed in this
+  branch", "help me instrument this diff", "check analytics coverage for this
+  change", or any request to start the analytics review workflow.
+---
+
+# diff-intake
+
+Follow this skill step by step.
+You are step 1 of the analytics instrumentation workflow. Produce a compact
+YAML change brief that downstream skills (discover-event-surfaces,
+instrument-events) will consume. Keep the output machine-readable and
+precise — no prose around the YAML block.
+
+## Step 1: Gather changed files and categorize
+
+Fetch the list of changed files from the source, then categorize each one.
+
+### Fetching changes
+- **PR URL**
+`gh pr view <number-or-url>`
+`gh pr view <pr-number> --json files --jq '.files[] | "\(.path)\t+\(.additions) -\(.deletions)\t"'`
+- **Branch comparison**
+`git log <main|master>..<branch>`
+`git diff --stat <main|master>..<branch>`
+- **Ambiguous mention** (PR number, branch name): infer the right form and fetch without asking unless auth fails.
+
+### Categorize files
+Assign each file to a category based on its path:
+- **Core Logic**: application source (e.g. src/auth/login.py, database/models.ts)
+- **Generated**: anything with `generated` in its path
+- **Testing**: test files
+- **Config / Dependencies**: package.json, docker-compose.yml, etc.
+- **Documentation**: READMEs, docs/
+- **Noise**: lock-files, .svg, auto-generated migrations
+
+For each file, record: path, category, change type (Added / Modified / Deleted), and analytics likelihood (1–5).
+
+## Step 2: Build the file summary map
+Read every single **Core Logic** file and create the file summary map.
+Only process and include **Core Logic** files.
+
+### Fetching detailed diffs
+- **PR**
+`gh pr view <number-or-url> --json baseRefOid,headRefOid`
+Using the response, get a detailed diff
+`git diff <baseRefOid>...<headRefOid> -- <file1> <file2> <file_n>`
+- **Branch comparison**
+`git diff main..feature/foo  -- <file1> <file2> <file_n>`
+
+### For each file, record
+- `summary` — 2-line summary of what changed
+- `stack` — frontend, backend, or shared
+
+### Also derive user-facing changes and touched surfaces
+
+While reading the diff and the changed files, also produce the higher-level
+signals that downstream event discovery needs:
+
+- `user_facing_changes` — a flat list of concrete behavior changes that matter
+  to a user, PM, or analyst. Each item should describe what a user can now do,
+  see, or experience differently. Omit purely internal refactors.
+- `surfaces.components` — the UI components, routes, pages, handlers, or other
+  interaction surfaces directly involved in those user-facing changes. Prefer
+  likely instrumentation points over low-level helpers.
+
+For each surface, record:
+- `name` — component, route, page, hook, or surface name
+- `file` — repo-relative path
+- `change` — `added`, `modified`, or `deleted`
+
+If the change is backend-only or has no clear interactive surface, omit
+`surfaces.components` rather than inventing one.
+
+## Step 3: Classify the overall change
+
+Infer the change type and analytics scope:
+
+| Type                                     | Analytics implication                             |
+| ---------------------------------------- | ------------------------------------------------- |
+| feat                                     | High — new surfaces likely need tracking          |
+| fix                                      | Low–Medium — may affect existing event conditions |
+| refactor                                 | Low — tracking paths may move, regression risk    |
+| perf                                     | Low — usually no tracking impact                  |
+| revert                                   | Medium — need to check what tracking was lost     |
+| style / docs / test / build / ci / chore | None — skip analytics analysis                    |
+
+`analytics_scope` = highest implication present:
+- `none` — only no-impact types
+- `low` — only perf/refactor
+- `medium` — fix
+- `high` — any feature or capability addition
+
+If `analytics_scope` is `none`, emit the brief and note that downstream skills are not needed.
+
+## Step 4: Emit the YAML brief
+Output only the YAML block — no prose before or after. Follow the format exactly.
+List each file individually in file_summary_map (no globs).
+
+```yaml
+change_brief:
+  classification:
+    primary: feat           # dominant conventional commit type
+    types: [feat, fix]      # all types detected
+    analytics_scope: high   # none | low | medium | high
+    stack: frontend         # frontend | backend | fullstack
+  summary: "One sentence describing the overall change"
+  user_facing_changes:
+    - "Users can now upload an avatar with drag-and-drop and preview it before saving."
+  surfaces:
+    components:
+      - name: "AvatarUpload"
+        file: "src/components/AvatarUpload.tsx"
+        change: modified
+  file_summary_map:         # each entry includes a layer field
+    - file: "src/components/AvatarUpload.tsx"
+      summary: "New component for avatar upload with drag-and-drop and preview"
+      layer: frontend       # frontend | backend | shared
+    - file: "src/api/upload.ts"
+      summary: "Upload endpoint handler, validates file type and persists to S3"
+      layer: backend
+```

package/skills/instrumentation/discover-analytics-patterns/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: discover-analytics-patterns
+description: >
+  Discovers how analytics tracking calls are actually written in this codebase —
+  the concrete SDK calls, function signatures, and import patterns used to send
+  events. Use this skill whenever you need to understand the existing analytics
+  instrumentation patterns before adding new tracking, when someone asks "how do
+  we track events here?", "show me the analytics setup", "what's the analytics
+  pattern in this codebase?", or any time the instrument-events or
+  discover-event-surfaces skills are about to run and you need to know the
+  correct coding style to follow. Outputs a deduplicated list of patterns with
+  generalized examples and the file paths where each pattern appears, plus the
+  dominant event and property naming conventions inferred from those call sites.
+  Always use this skill before writing any analytics instrumentation code.
+---
+
+# discover-analytics-patterns
+
+Your goal is to find out **how** this codebase sends analytics events — not which
+events exist, but the specific code patterns engineers use to fire a tracking
+call. This output helps engineers add new events that look consistent with the
+rest of the codebase. It should also tell downstream skills how event names and
+property names are typically written in code here.
+
+When determining naming conventions in this skill, use the following sources in strict order of preference:
+1. Events and properties observed from the Amplitude MCP server
+2. Real tracking call sites in the codebase
+3. The `taxonomy` skill at `../../taxonomy/amplitude-quickstart-taxonomy-agent/SKILL.md`
+
+---
+
+## Step 1: Find tracking calls
+
+Use two approaches based on what's available.
+
+### If the Amplitude MCP is connected
+
+Call `get_events` (or equivalent) to fetch a sample of event names from the
+project. Use those results to choose a few representative non-system product
+events, then call `get_event_properties` for those events to inspect real
+property names. This is your primary naming reference.
+
+Do not infer naming conventions from bracket-prefixed Amplitude system names
+such as `[Amplitude], [Guides-Surveys], [Assistant], [Experiment]` for either events or properties. Exclude those from
+pattern detection. If the MCP sample is dominated by Amplitude system names or otherwise does not provide enough evidence, fall back to codebase
+inference for naming.
+
+Then search the codebase for the sampled non-system event names using Grep to
+locate the actual tracking call sites.
+
+### If the Amplitude MCP is not available (fallback)
+
+Search the codebase for these signals using Grep. Cast a wide net — you can
+narrow down after:
+
+| What to search for                                       | Why                                               |
+| -------------------------------------------------------- | ------------------------------------------------- |
+| `\.track\(`                                              | Generic `.track()` method calls                   |
+| `ampli\.`                                                | Ampli typed SDK calls (e.g. `ampli.myEvent(...)`) |
+| `amplitude\.track\|amplitude\.logEvent`                  | Direct Amplitude SDK calls                        |
+| `sendEvent`                                              | Custom wrapper method names                       |
+| `from.*amplitude\|import.*amplitude\|require.*amplitude` | Import statements                                 |
+| `https://api2\.amplitude\.com/2/httpapi`                 | HTTP API calls                                    |
+
+Also actively look for custom analytics wrappers — a codebase often wraps the
+raw SDK in a utility like `trackEvent()`, `track()`, or a React hook like
+`useAnalytics()` or `useTracking()`. Search for these by looking for functions
+that call into Amplitude internally. **Treat each wrapper as its own pattern,
+separate from the underlying SDK call**, even if it ultimately calls
+`amplitude.track()` underneath. Engineers who encounter the wrapper will use
+*it*, not the raw SDK — so it's the more important pattern to document.
+
+To find wrappers: search for files that import the Amplitude SDK, then check
+whether any of those files export a function or hook that other parts of the
+codebase import and use for tracking.
+
+Exclude test files (`.test.`, `.spec.`, `__tests__`) and mock files unless they
+are the *only* place a pattern appears.
+
+---
+
+## Step 2: Group by pattern
+
+Two call sites use the **same pattern** if they share the same:
+- Library/SDK/function being called
+- Method name
+- Argument structure (even if the event name or properties differ)
+
+For example, these are the **same** pattern:
+```ts
+amplitude.track('Page Viewed', { page: '/home' })
+amplitude.track('Button Clicked', { label: 'signup' })
+```
+
+But these are **different** patterns — always keep them separate:
+```ts
+amplitude.track('Page Viewed', { page: '/home' })   // direct SDK — one pattern
+ampli.pageViewed({ page: '/home' })                  // Ampli typed method — different pattern
+trackEvent('Page Viewed', { page: '/home' })         // custom wrapper — also a separate pattern
+```
+
+A custom wrapper is always its own pattern, even if it delegates to the SDK
+underneath. When documenting a wrapper pattern, note what it wraps (e.g.,
+"Custom hook wrapping `amplitude.track()`") so engineers understand the layering.
+
+---
+
+## Step 3: Resolve naming conventions
+
+Resolve two conventions separately:
+
+- `event_naming_convention` — casing, separators, word order, prefixes, and
+  tense used for event names in instrumentation code. Examples: `Title Case`,
+  `snake_case`, `[Prefix] Action`, object-first vs action-first.
+- `property_naming_convention` — casing, separators, and common suffix/prefix
+  patterns used for event properties. Examples: `snake_case`, `camelCase`,
+  `*_id`, `is_*`, flat keys vs nested objects.
+
+Use this precedence order:
+
+1. **Amplitude MCP first.** If the observed `eventType` values and
+   property names returned by `get_event_properties` for a few representative
+   non-system events show a clear dominant convention, use that. Do not use
+   bracket-prefixed Amplitude system names as naming evidence.
+2. **Codebase second.** If the MCP evidence is unavailable, sparse, or
+   inconsistent, infer the dominant convention from nearby, real tracking call
+   sites in the repository. If the codebase shows multiple conventions, call
+   out the dominant one and note meaningful local exceptions.
+3. **Taxonomy fallback last.** If neither MCP nor codebase evidence is
+   clear enough, fall back to the `taxonomy` skill at `../../taxonomy/amplitude-quickstart-taxonomy-agent/SKILL.md`.
+
+Do not guess. If one or both conventions remain unclear even after checking
+those sources, say so explicitly.
+
+---
+
+## Step 4: Output
+
+Start with a short conventions section, then list each unique pattern.
+
+```yaml
+event_naming_convention: "<from MCP if clear, otherwise codebase, otherwise taxonomy skill, or 'insufficient evidence'>"
+property_naming_convention: "<from MCP if clear, otherwise codebase, otherwise taxonomy skill, or 'insufficient evidence'>"
+```
+
+Then, for each unique pattern, output a section in this format:
+
+---
+
+### Pattern: `<short descriptive name>`
+
+**Description**: What this pattern does and when it's typically used in this
+codebase (e.g., "Used throughout the React frontend for user action tracking").
+
+**Example** (generalized):
+```<language>
+// show the import(s) needed
+import { amplitude } from '@/lib/analytics'
+
+// show a representative tracking call with placeholder names
+amplitude.track('Event Name', {
+  propertyOne: value,
+  propertyTwo: value,
+})
+```
+
+**Relevant paths**:
+- `src/path/to/file.ts`
+- `src/another/file.tsx`
+
+---
+
+List patterns from most common (most file paths) to least common.
+
+If two patterns are always used together (e.g., an import + a call), show them
+together in one example.
+
+---
+
+## Step 5: Handle no results
+
+If no tracking calls are found with any search strategy, say so clearly. Suggest
+that the user check whether Amplitude (or another analytics library) has been set
+up in the project, and offer to search for other analytics libraries (Segment,
+Mixpanel, PostHog, etc.) if relevant.