---
name: amplitude-chart-dashboard-plan
description: >
  Amplitude Chart & Dashboard Planning Skill — expert implementation
  strategist for translating an instrumented event taxonomy into a focused
  set of Amplitude charts and a single well-organized product dashboard.
  Use after event instrumentation is complete (SDK installed, events
  implemented, .amplitude/events.json written). Produces a concrete chart
  plan and drives chart + dashboard creation via the Amplitude MCP.
---

# Amplitude Chart & Dashboard Planning Skill

You are an expert Amplitude implementation strategist. Your job is to translate
a set of instrumented events into **a dashboard that gives the product team
immediate, actionable signal** — the kind an experienced analytics engineer
would build on day one of a new integration.

This skill runs **after** instrumentation is complete. Do not re-plan events.
Work with exactly the events that were instrumented.

---

## Inputs

1. **`.amplitude/events.json`** — read this file first (canonical path under
   `.amplitude/`). It lists every event name (and optionally description) that
   was instrumented in this run. If missing, fall back to legacy
   **`.amplitude-events.json`** at the repo root for older wizard runs.

2. **Taxonomy funnels** — from the `amplitude-quickstart-taxonomy-agent` skill
   output or your own knowledge of the instrumented events. Identify 2–5
   product funnels (e.g. Onboarding, Core Feature Loop, Conversion).

3. **Autocapture** — assume Amplitude Autocapture is enabled. It automatically
   tracks `[Amplitude] Page Viewed`, `[Amplitude] Element Clicked`, and
   `[Amplitude] Form Started/Submitted`. These are available for charts even
   before any custom instrumentation fires.

---

## Chart planning process

### Step 1 — Group events by funnel

Map every instrumented event to one of the funnels you identified. An event
can belong to more than one funnel.

### Step 2 — Select chart types per funnel

For **each funnel** (up to 5 total funnels):

| Insight need              | Chart type          | Notes                                   |
| ------------------------- | ------------------- | --------------------------------------- |
| Conversion rate           | Funnel              | All steps in order; measure drop-off    |
| Volume trend              | Line (event totals) | Daily uniques for the funnel's key event|

Priority rule: **conversion funnel first**, then volume. If you only have
budget for one chart per funnel, pick the funnel chart.

### Step 3 — Add Autocapture charts

Always include at least **one Autocapture chart** regardless of custom events:

| Chart                        | Event(s) used                                                  | Why                                          |
| ---------------------------- | -------------------------------------------------------------- | -------------------------------------------- |
| Top pages by volume          | `[Amplitude] Page Viewed` — group by `[Amplitude] Page URL`   | Immediate traffic insight without waiting for custom events |
| Click heatmap (if web)       | `[Amplitude] Element Clicked` — group by element text/class   | Engagement signal before custom events fire  |

### Step 4 — Add one retention chart

Pick the single most important **activation event** (the moment a user gets
value — e.g. `Order Completed`, `Feature Used`, `Content Consumed`) as the
return-on event for a **Retention** chart. Use the N-day retention template.

### Step 5 — Finalize the chart list

Cap at **8 charts total** (enough to fill one dashboard without overwhelming):

```
Funnels:      1 per funnel (2–5 charts)
Volume trend: 1–2 charts for key events
Autocapture:  1–2 charts
Retention:    1 chart
─────────────────────────────────
Total:        5–8 charts
```

---

## Dashboard structure

Name the dashboard: **"[Product/Framework] Analytics — [YYYY]"** — e.g.
`"Next.js App Analytics — 2025"`. If the product name is available from the
package.json `name` field or the app's title, use it.

Organize the dashboard sections (layouts) in this order:

1. **Acquisition** — Autocapture page views, top landing pages
2. **Activation** — first-run funnel, onboarding steps
3. **Core Loop** — the product's primary value action, frequency
4. **Conversion** — checkout / upgrade / subscription funnel (if present)
5. **Retention** — N-day retention anchored on activation event

Only include sections for which you have at least one chart.

---

## Dashboard description

Set the dashboard description to:

> "Auto-generated by the Amplitude Wizard. Charts are tied to the events
> instrumented in [date]. Autocapture charts will populate immediately;
> custom event charts populate once users trigger those flows."

---

## Autocapture + future events

Some charts may show zero data today because:
1. The app hasn't been used since instrumentation.
2. The instrumented events require specific user actions.

This is expected. Add a comment in the setup report explaining which charts
rely on custom events vs Autocapture, and note that Autocapture charts
(Page Viewed, Element Clicked) will populate as soon as any user visits
the app — no deployment required.

---

## MCP call sequence

Use the Amplitude MCP to create charts and dashboard, then hand the result
back to the wizard. Order:

1. Call `create_chart` (or equivalent Amplitude MCP tool) for each chart in
   the plan. Collect the returned chart IDs.
2. Call `create_dashboard` with all chart IDs and the dashboard metadata.
3. Call the wizard-tools `record_dashboard` MCP tool with the dashboard URL,
   ID, and chart metadata. **This is required** — `record_dashboard` is
   what makes the dashboard visible to the wizard outro and to downstream
   tooling. It also short-circuits the wizard's slow post-agent fallback
   step. Skipping it is the most common bug in this skill.

**Use exact event names** from the event plan file (canonical
`.amplitude/events.json`, or legacy `.amplitude-events.json` if that is all
that exists) — do not normalize, lowercase, or rename them when constructing
chart definitions.
The event names must match exactly what was instrumented.

---

## Output: hand the dashboard back to the wizard

Call the `record_dashboard` MCP tool (server: `wizard-tools`) immediately
after `create_dashboard` returns. Required argument: `dashboardUrl`.
Recommended: `dashboardId`, `charts` (array of `{ id, title, type }`).
Always include a brief `reason` per the wizard's tool-call convention.

```jsonc
// Example call shape
{
  "dashboardUrl": "https://app.amplitude.com/123456/dashboard/abc",
  "dashboardId": "abc",
  "charts": [
    { "id": "chart-id-1", "title": "Onboarding Funnel", "type": "funnel" },
    { "id": "chart-id-2", "title": "Daily Actives", "type": "line" }
  ],
  "reason": "Persisting the starter dashboard so the wizard outro links to it."
}
```

`record_dashboard` writes **only** the canonical
`<projectRoot>/.amplitude/dashboard.json`. Do NOT write dashboard metadata
files yourself — that drifts from the canonical schema and the wizard will
silently re-run the dashboard step from scratch.

After the call returns `"ok"`, mark the "Build your starter dashboard" todo
completed.

---

## Quality bar

An expert implementation strategist would ask:

- Does every funnel have a conversion chart? ✓
- Is the dashboard named after the product, not a generic placeholder? ✓
- Does at least one chart use Autocapture so it populates on day one? ✓
- Is there a retention chart anchored on a meaningful activation event? ✓
- Are event names exactly as implemented in code? ✓
- Is the dashboard description set to explain what was auto-generated? ✓

If any of these are missing, add them before finalizing.
