@amplitude/wizard 1.0.0 → 1.2.0

package/skills/taxonomy/amplitude-chart-dashboard-plan/SKILL.md

@@ -0,0 +1,183 @@
+---
+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.

package/dist/src/ui/tui/screens/ChecklistScreen.d.ts

@@ -1,12 +0,0 @@
-/**
- * ChecklistScreen — Post-setup checklist for first chart and dashboard.
- *
- * Shown after DataIngestionCheckScreen confirms events are flowing.
- * Celebration header: "Your events are flowing!" in success green.
- */
-import type { WizardStore } from '../store.js';
-interface ChecklistScreenProps {
-    store: WizardStore;
-}
-export declare const ChecklistScreen: ({ store }: ChecklistScreenProps) => import("react/jsx-runtime").JSX.Element;
-export {};

package/dist/src/ui/tui/screens/ChecklistScreen.js

@@ -1,111 +0,0 @@
-import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
-/**
- * ChecklistScreen — Post-setup checklist for first chart and dashboard.
- *
- * Shown after DataIngestionCheckScreen confirms events are flowing.
- * Celebration header: "Your events are flowing!" in success green.
- */
-import { Box, Text } from 'ink';
-import { useEffect, useState } from 'react';
-import { useWizardStore } from '../hooks/useWizardStore.js';
-import { Colors, Icons } from '../styles.js';
-import { PickerMenu } from '../primitives/index.js';
-import { OUTBOUND_URLS } from '../../../lib/constants.js';
-import opn from 'opn';
-import { analytics } from '../../../utils/analytics.js';
-import { fetchOwnedDashboards } from '../../../lib/api.js';
-export const ChecklistScreen = ({ store }) => {
-    useWizardStore(store);
-    const { session } = store;
-    const { checklistChartComplete, checklistDashboardComplete, region, selectedOrgId, } = session;
-    const [opening, setOpening] = useState(null);
-    const zone = (region ?? 'us');
-    // On mount, detect charts/dashboards the user already owns so returning
-    // users see the correct state without re-doing completed steps.
-    useEffect(() => {
-        const { credentials, selectedOrgId, checklistChartComplete, checklistDashboardComplete, } = store.session;
-        if (!credentials || !selectedOrgId)
-            return;
-        if (checklistChartComplete && checklistDashboardComplete)
-            return;
-        const accessToken = credentials.accessToken;
-        const sessionZone = (store.session.region ?? 'us');
-        fetchOwnedDashboards(accessToken, sessionZone, selectedOrgId)
-            .then(({ hasCharts, hasDashboards }) => {
-            if (hasCharts)
-                store.setChecklistChartComplete();
-            if (hasDashboards)
-                store.setChecklistDashboardComplete();
-        })
-            .catch(() => {
-            // fetchOwnedDashboards never rejects — handled defensively
-        });
-    }, []);
-    const chartUrl = OUTBOUND_URLS.newChart(zone, selectedOrgId);
-    const dashboardUrl = OUTBOUND_URLS.newDashboard(zone, selectedOrgId);
-    function openInBrowser(url, item) {
-        setOpening(item);
-        analytics.wizardCapture('Checklist Step Opened', { item });
-        opn(url, { wait: false })
-            .catch(() => {
-            /* fire-and-forget */
-        })
-            .finally(() => {
-            setOpening(null);
-            if (item === 'chart')
-                store.setChecklistChartComplete();
-            if (item === 'dashboard')
-                store.setChecklistDashboardComplete();
-        });
-    }
-    function handleSelect(value) {
-        switch (value) {
-            case 'chart':
-                openInBrowser(chartUrl, 'chart');
-                break;
-            case 'dashboard':
-                openInBrowser(dashboardUrl, 'dashboard');
-                break;
-            case 'continue':
-                store.setChecklistComplete();
-                break;
-        }
-    }
-    const allDone = checklistChartComplete && checklistDashboardComplete;
-    const options = [
-        {
-            value: 'chart',
-            label: checklistChartComplete
-                ? `${Icons.checkmark} Build a chart — done`
-                : `${Icons.bulletOpen} Build your first chart`,
-            hint: checklistChartComplete ? undefined : 'opens in browser',
-            disabled: checklistChartComplete,
-        },
-        {
-            value: 'dashboard',
-            label: checklistDashboardComplete
-                ? `${Icons.checkmark} Create a dashboard — done`
-                : `${Icons.bulletOpen} Create your first dashboard`,
-            hint: checklistDashboardComplete
-                ? undefined
-                : checklistChartComplete
-                    ? 'opens in browser'
-                    : 'build a chart first',
-            disabled: checklistDashboardComplete || !checklistChartComplete,
-        },
-        {
-            value: 'taxonomy',
-            label: `${Icons.bulletOpen} Set up taxonomy`,
-            hint: 'coming soon',
-            disabled: true,
-        },
-        {
-            value: 'continue',
-            label: allDone
-                ? `${Icons.arrowRight} Done — continue`
-                : `${Icons.arrowRight} Skip and continue`,
-            hint: allDone ? undefined : 'you can always do these later',
-        },
-    ];
-    return (_jsxs(Box, { flexDirection: "column", flexGrow: 1, paddingX: 2, paddingY: 1, children: [_jsxs(Box, { marginBottom: 1, flexDirection: "column", children: [_jsxs(Text, { bold: true, color: Colors.success, children: [Icons.checkmark, " Your events are flowing!"] }), _jsx(Text, { color: Colors.body, children: "Here's what to explore next:" })] }), opening && (_jsx(Box, { marginBottom: 1, children: _jsxs(Text, { color: Colors.muted, children: ["Opening Amplitude in your browser", Icons.ellipsis] }) })), _jsx(PickerMenu, { options: options, onSelect: (v) => handleSelect(v) })] }));
-};