diff --git a/context/skills/integration/references/4-conclude.md b/context/skills/integration/references/4-conclude.md index 61f21af..2fe51d0 100644 --- a/context/skills/integration/references/4-conclude.md +++ b/context/skills/integration/references/4-conclude.md @@ -70,6 +70,21 @@ Valid `trendsFilter.display` values are `ActionsLineGraph`, `ActionsBar`, `Actio Once the dashboard exists, emit its URL on its own line in your assistant message using this exact marker: `[DASHBOARD_URL] `. The wizard parses this marker from your visible message and surfaces the link in the success summary. Mentioning the URL only in thinking or in prose without the marker means the link is dropped. +### Set up a subscription and alerts so the dashboard reaches an inbox + +This step schedules a real recurring email and enrols the user in alert notifications — standing side effects beyond the code integration they asked for, so get consent first. + +**Ask before creating anything.** Tell the user you'd like to set up a weekly email digest of the new dashboard plus up to two alerts on its highest-signal insights, say in one line what each is, and get a yes/no. If they decline, skip this whole section. + +On a yes, call `user-get` with uuid `@me` for the current user's id and email. If no email comes back (service account, unusual SSO), skip the subscription — don't invent a recipient, note the skip in the report — and still create the alerts, which key off the id, not the email. + +1. **One dashboard subscription (`subscriptions-create`).** Weekly email digest of the dashboard just created: `target_type: "email"`, `target_value` set to the user's email from `user-get`, `dashboard` set to the new dashboard id, `dashboard_export_insights` set to up to 6 of its insight ids (or fewer if the dashboard has fewer), `frequency: "weekly"`, `interval: 1` (every 1 week), `start_date` set to now. Leave `summary_enabled` off — enabling AI summaries needs its own separate human OK that this consent didn't cover. +2. **One or two insight alerts (`alert-create`)**, only on the insight(s) that would actually cost the business something if they moved the wrong way — a conversion funnel dropping, a churn/drop-off event spiking, signups stalling. Skip "nice to watch" insights (e.g. a raw pageview count), and if nothing on the dashboard clearly qualifies, create zero rather than padding to the ceiling. For a funnel step, use `condition: { type: "relative_decrease" }` with a `FunnelsAlertConfig`; for a trend that should stay above/below a bound, use a `TrendsAlertConfig` with `threshold.configuration.bounds`. Set `subscribed_users` to `[]` (the integer id, not the uuid) and `calculation_interval: "daily"` unless the insight's own interval argues for something coarser. + +The create calls return the new records but not a link, so build each URL with `generate-app-url` from the ids you just got back — never hand-construct these paths. For the subscription, `call generate-app-url` with `url` set to `/dashboard/{id}/subscriptions/{subscriptionId}` and `params` `{ "id": , "subscriptionId": }`. For each alert, `call generate-app-url` with `url` set to `/insights/{insightShortId}/alerts` and `params` `{ "insightShortId": }`. + +When writing the setup report, briefly explain what a subscription is (a recurring email snapshot of the dashboard) and what an alert is (a one-off email the moment a specific metric crosses a threshold), and name which insight(s) got an alert and why they were judged the highest-signal ones. + Search for a file called `.posthog-events.json` and read it for available events. Do not spawn subagents. @@ -89,6 +104,10 @@ We've built some insights and a dashboard for you to keep an eye on user behavio [links] +[one line explaining the dashboard subscription: what it is, cadence, and which email it goes to, with a link to it in PostHog] + +[one line per alert: which insight it watches, the condition, that it emails on breach, why that metric moving is worth caring about, and a link to it in PostHog] + ## Verify before merging [checklist] @@ -107,6 +126,7 @@ For the "Verify before merging" checklist, write GitHub-style checkboxes (`- [ ] - If this integration ships a minified production browser bundle (most SPA/SSR web frameworks — e.g. Next.js, Nuxt, SvelteKit, Astro, Vite-based apps): "Wire source-map upload (`posthog-cli sourcemap` or your bundler's upload step) into CI so production stack traces de-minify." - If LLM analytics was set up in this run: "Trigger the LLM call path(s) you instrumented and confirm `$ai_generation` events appear in PostHog AI Observability." - If the app has user auth and an `identify` call was added: "Confirm the returning-visitor path also calls `identify` — a handler that only identifies on fresh login can leave returning sessions on anonymous distinct IDs." +- Always (if a subscription or alert was created): "Check the dashboard subscription and alert(s) went to the right inbox and cadence — the wizard defaulted to your account email and a weekly/daily schedule." Do not invent items beyond what applies. If only the two "Always" items apply, the checklist is just those two. @@ -119,5 +139,7 @@ Upon completion, update `.posthog-events.json` so it matches the events you actu Status to report in this phase: - Configured dashboard: [insert PostHog dashboard URL] +- Configured dashboard subscription: [recipient email, frequency] +- Configured alert(s): [insight name(s), condition] - Created setup report: [insert full local file path] - Created notebook: [insert PostHog notebook URL]