---
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. It lists every event
   name (and optionally description) that was instrumented in this run.

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. Suggested order:

1. Call `create_chart` (or equivalent 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. Record the returned dashboard URL.

**Use exact event names** from `.amplitude-events.json` — do not
normalize, lowercase, or rename them when constructing chart definitions.
The event names must match exactly what was instrumented.

---

## Output: what to write to `.amplitude-dashboard.json`

After dashboard creation, write a file named `.amplitude-dashboard.json` in
the project root with this shape (replace with real values):

```json
{
  "dashboardUrl": "https://app.amplitude.com/123456/dashboard/abc",
  "dashboardId": "abc",
  "charts": [
    {
      "id": "chart-id-1",
      "title": "Onboarding Funnel",
      "type": "funnel",
      "funnel": "Onboarding"
    }
  ],
  "createdAt": "2025-01-15T12:00:00Z"
}
```

This file is read by the wizard to surface the dashboard URL in the checklist.
It is also listed in the setup report. Remove it after the setup report is
written (same as `.amplitude-events.json`).

---

## 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.
