From e962c1c6ae429abf1a5299e0f218c96544b99f44 Mon Sep 17 00:00:00 2001 From: Matt Pua Date: Fri, 10 Jul 2026 11:57:34 -0400 Subject: [PATCH 1/3] docs: add subscription and alert setup guidance to integration conclusion phase Generated-By: PostHog Code --- .claude/settings.local.json | 1 + .../integration/references/4-conclude.md | 22 +++++++++++++++++++ 2 files changed, 23 insertions(+) create mode 100644 .claude/settings.local.json diff --git a/.claude/settings.local.json b/.claude/settings.local.json new file mode 100644 index 00000000..0967ef42 --- /dev/null +++ b/.claude/settings.local.json @@ -0,0 +1 @@ +{} diff --git a/context/skills/integration/references/4-conclude.md b/context/skills/integration/references/4-conclude.md index 8a8689bb..ac8dedcd 100644 --- a/context/skills/integration/references/4-conclude.md +++ b/context/skills/integration/references/4-conclude.md @@ -58,6 +58,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 current user's id and `calculation_interval: "daily"` unless the insight's own interval argues for something coarser. + +Capture the `_posthogUrl` (or equivalent URL field) each create call returns; if one doesn't return it, get the link via `generate-app-url`. Never hand-construct these paths. + +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. @@ -77,6 +92,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] @@ -95,6 +114,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. @@ -105,4 +125,6 @@ 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] From 430ab01f9511754e6cc4fb2d062e3738a0633bfb Mon Sep 17 00:00:00 2001 From: Matt Pua Date: Fri, 10 Jul 2026 12:00:00 -0400 Subject: [PATCH 2/3] chore: drop local settings file from branch Generated-By: PostHog Code Task-Id: 661dc901-93df-4bcf-a705-472aea8622aa --- .claude/settings.local.json | 1 - 1 file changed, 1 deletion(-) delete mode 100644 .claude/settings.local.json diff --git a/.claude/settings.local.json b/.claude/settings.local.json deleted file mode 100644 index 0967ef42..00000000 --- a/.claude/settings.local.json +++ /dev/null @@ -1 +0,0 @@ -{} From d2139cf45526eac6e163bf83f89158cf68fd9474 Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Wed, 15 Jul 2026 10:01:24 -0400 Subject: [PATCH 3/3] fix(integration): build subscription/alert links via generate-app-url create calls don't return a URL field (only list calls do), so the conclusion step now derives each link from generate-app-url catalog templates using the ids from subscriptions-create / alert-create, and clarifies subscribed_users takes the numeric user id. Generated-By: PostHog Code Task-Id: eec3ed23-16ee-4b68-9aab-94ab7a87174a --- context/skills/integration/references/4-conclude.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/context/skills/integration/references/4-conclude.md b/context/skills/integration/references/4-conclude.md index d7d07d29..2fe51d01 100644 --- a/context/skills/integration/references/4-conclude.md +++ b/context/skills/integration/references/4-conclude.md @@ -79,9 +79,9 @@ This step schedules a real recurring email and enrols the user in alert notifica 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 current user's id and `calculation_interval: "daily"` unless the insight's own interval argues for something coarser. +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. -Capture the `_posthogUrl` (or equivalent URL field) each create call returns; if one doesn't return it, get the link via `generate-app-url`. Never hand-construct these paths. +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.