Enhance onboarding playbook with account audit notebooks and better language (#17545)

Added examples of effective CTAs and phrases to avoid in onboarding communications. Expanded on the account audit prompt, and offering notebooks for customer engagement.

Author: molszewska

contents/handbook/onboarding/onboarding-conversations-playbook.md

@@ -43,12 +43,12 @@ Use the following product signals:
 - **General value offer (audit / review)**
   - “Quick data audit from the Onboarding team”
   - “Tracking review: 3 improvements I’d make”
-  - “Want me to sanity-check your {events / funnels / flags}?”
+  - “Want me to sanity-check your events / funnels / flags?”
   - “Data audit: 3 tracking gaps I’d fix first”
   - “I recorded a 2-min walkthrough for your setup”
   - “A recommended dashboard for [their use case]”
   - “Worth a look before your next release”
-  ​​- “Are you trying to do [goal]? (I can help)”
+  - "Are you trying to do [goal]? (I can help)”
 
 ### Content
 
@@ -58,6 +58,16 @@ Use the following product signals:
 
 **Use prior context to be proactive**. Before you hit send, take a minute to scan prior threads. If a customer spoke with Sales during an evaluation, check what came up and reference it (e.g., “I saw you covered X with [Name]”) so your email feels connected. And look for other loose ends too, e.g., an old support ticket, or a question from months ago. Following up with a real solution feels personal, and proactive delight gets noticed.
 
+**Good CTAs**
+- "Want to take a look together?"
+- "Want to compare notes on what's working?"
+- " Worth a look before your next renewal?"
+- "Happy to help if the timing is right."
+
+**Vibe killers (never use)**
+"circling back" · "just touching base" · "hope this finds you well" · "I'd love to connect" · "I'm genuinely
+curious" · "are you open to a quick chat?" · "let me know your thoughts" · "synergy" · "leverage" · "alignment" · "best-in-class".
+
 ### Checking in
 
 This is where we can have a real impact on product adoption and usage expansion. Think of it as a value-driven "soft cross-sell". 
@@ -70,6 +80,13 @@ Don’t just repeat yourself. Avoid rehashing the same observations from your fi
 Mainly, help them get to an “aha” moment, and/or suggest one or two features they’d benefit from, but may not have discovered or had time to try.
 PostHog features become more powerful when used together (e.g., funnels/error tracking + session replay + PostHog AI). Share a specific guide, an example, or a Loom video, so the customer doesn’t have to poke around to figure it out. You can take some inspiration from [Use Case Selling handbook pages](https://posthog.com/handbook/growth/use-case-selling/use-case-selling).
 
+A very powerful way to engage the customer and provide value is to run an account audit prompt on their account and save the findings as a notebook for them. The prompt creates a readable, easy-to-follow guide on the areas the customer might not have thought about before. This also works really well as an additional post-meeting resource!
+
+<details>
+<summary>Account audit prompt</summary>
+You are auditing this customer's PostHog account to produce a notebook they will read directly. Use the last 30 days of data unless noted. The customer will see this output, so write it for them, not for an internal PostHog reviewer. ## Internal analysis (do NOT output) Before writing the notebook, infer for yourself: - Customer's business and product type (from event names, URLs, person properties) - Stack (SDKs, frameworks) - Approximate scale and product maturity - Likely cost drivers Use this context to sharpen recommendations. Do NOT write these inferences into the notebook. The customer knows their business. ## Notebook structure Open with a brief summary, 2 to 3 lines in plain language: - A one-line headline that names the most important finding or finding count. - One or two more lines highlighting what the customer should know first. Then the audit, then recommendations, then untapped opportunities. No "Step 1" or "Phase N" labels in headings. ## Audit Run checks across every PostHog product below. Checks are exhaustive; output is filtered. Surface a finding only if it is (a) actionable, (b) notably healthy, or (c) anomalous. Skip dimensions where nothing stands out. For every product dimension (everything except Instrumentation health and Cost drivers): if the product is not in use, evaluate whether the customer would benefit from it given the business and stage you inferred. If yes, surface as a finding (:large_yellow_circle: "could help" or :red_circle: "major gap" depending on severity). This makes "should they adopt this?" a first-class question for every product. One exception: Revenue analytics is a retired PostHog product, so never recommend adopting it; when revenue tracking is the gap, recommend connecting a billing source (Stripe, etc.) as a data warehouse source and building custom insights or SQL queries that join revenue with product data. Prefix every finding with: - :large_green_circle: Working well - :large_yellow_circle: Worth attention - :red_circle: Needs action ### Common pitfalls (verify before reporting) - **Sessions vs session recordings**: The `sessions` table contains every user session regardless of whether session replay is enabled. Session recordings only exist when replay is explicitly turned on. Before reporting any volume as "recordings," verify session replay is enabled on the project (check `session_recording_opt_in` on the team, or confirm `session_recording` data actually exists). NEVER describe `sessions` table counts as "recordings." - **Events vs actions**: Events are raw; actions are named/filtered groupings of events. Do not conflate. Absence of Actions is NOT absence of events; it is an autocapture-optimization opportunity (flag only if autocapture is a significant % of volume AND zero Actions are defined). - **`distinct_id` vs `person_id`**: A single person can have many distinct_ids (post-identify merge). When counting "users," confirm which level the query is returning. - **Identified vs anonymous persons**: Anonymous persons are still persons in PostHog's data model. "Total persons" includes both. ALSO: backend and server-side SDKs always create identified events by design, and logged-in product subdomains will be near-100% identified. Only flag a "low anonymous ratio" as a problem for web SDK traffic on public or marketing sites; do not flag it for backend SDKs or logged-in apps. - **Internal and test users inflate everything**: Most customers have an internal or test cohort (e.g. `$internal_or_test_user = true`, or email-domain filtering). Before reporting DAU/WAU, engagement, top events, or per-user metrics, exclude internal/test traffic if such a cohort exists. If unclear, check whether the top distinct_ids look like company-domain emails. - **Bot traffic**: PostHog auto-excludes known bots from billing, but raw event tables (`events`, `sessions`) still contain them. For "unique users," DAU, or engagement counts, apply the same bot exclusion the project uses (`bot_user_agents` team setting plus the standard `$browser` check) before reporting numbers. - **Billing limits cap volumes**: If a product is at or near its billing limit, observed event/recording volume is artificially capped. Events past the limit are DROPPED, not queued. Check whether the team has `billing_limits` set before describing observed volume as "natural" or recommending optimizations against an already-capped baseline. - **Session replay sampling**: If `sampleRate` is below 1.0, recording counts are a sample of total sessions, not all of them. Always report the sample rate alongside recording-volume claims, or you will understate true session activity. - **`$ai_*` events have multiple sources**: `$ai_generation`, `$ai_span`, and `$ai_trace` fire from (a) the customer instrumenting LLM observability on their own product, AND (b) anyone using PostHog AI or Max inside the project (including admins running ad-hoc queries). Confirm the events come from real product users (check distinct_ids, not just volume) before reporting them as "customer AI feature adoption." - **Low-volume events are not always broken**: Some events (payment failures, deletion confirmations, rare admin actions) fire infrequently by design. Do not flag a custom event as "deprecated" based purely on volume; check the event-name pattern first. ### Dimensions to check (14 total, covering every PostHog product) 1. **Instrumentation health**: SDKs in use, autocapture vs custom event ratio, duplicate or redundant events, low-volume events that may be broken (cross-check with the pitfalls list), identified vs anonymous ratio (apply the backend-SDK caveat), person property update frequency, `identify()` call patterns (anti-pattern: called on every page load instead of only on auth), group analytics (for B2B). 2. **Product analytics**: top events, common paths, week-over-week retention, drop-off points, DAU/WAU, dashboards, alerts, subscriptions. 3. **Web analytics**: enabled, data flowing, conversion goals, core web vitals. 4. **Session replay and heatmaps**: First confirm session replay is actually enabled (see Common pitfalls). Then: recording volume (note sample rate if set), average duration, minimum duration filter, rage and dead clicks, heatmap usage. 5. **Feature flags**: total, active vs stale, evaluation distribution, server vs client, flags at 100% for over 30 days, flag-shaped use cases that should be experiments. Note: unused flags still bill until archived in the PostHog UI (removing from code alone is not enough). Local-evaluation polling can be a silent billing driver; check polling cadence. 6. **Experiments**: in use, sample sizes, statistical health. 7. **Surveys**: in use, response rates, targeting. 8. **Error tracking**: capturing exceptions, grouping, issue assignment, alerts. 9. **LLM observability**: `$ai_generation`, `$ai_trace` events (apply the multi-source caveat), generations, traces, cost and latency tracking for AI features. 10. **Data warehouse**: external sources connected (Stripe, Postgres, etc.), sync health, joins with event data. 11. **CDP / Data pipelines (destinations)**: events exported to BigQuery, Snowflake, Hubspot, Salesforce, etc.; Hog functions and transformations in use. Note: transformations only affect future events; past data is unchanged. 12. **Revenue tracking**: is billing or revenue data connected and joined to product usage? Do NOT recommend the retired Revenue analytics product. The play is to connect a billing source (Stripe, Chargebee, etc.) as a data warehouse source, then build custom insights or SQL queries that join revenue with event data (MRR/ARR by feature, expansion, churn signals). Check whether a billing source is connected, syncing, and joined to product data. 13. **Cohorts**: count, static vs dynamic, used in flags/experiments/surveys/insights. Anti-pattern: dynamic cohorts targeted at experiments, flags, or surveys do not work (the cohort must be duplicated as static first). 14. **Cost drivers**: which products, events, or patterns drive the most volume on THIS account. Reference findings from other sections rather than repeating them. Diagnose from the data, not from generic rules. Account for billing limits and sampling when computing "true" volumes. Each finding appears in exactly ONE section. No duplication across dimensions. ## Recommendations Single numbered list, ranked by impact then effort. Top 5 only. For each: - The specific action, named. - Why it matters, in plain language. - Estimated impact in numbers (event count, % reduction, etc.) ONLY when you can compute it from the data. If you cannot, skip the number; do not guess. - Link to the relevant PostHog docs page. No P0/P1/P2 labels. No category headers like "Billing reduction" or "Activation lift." One tight paragraph per recommendation, 3 sentences maximum. ## Untapped opportunities 3 to 5 strategic plays the customer should consider next, given the business and stage you inferred. Forward-looking and creative, NOT a recap of products already flagged as missing in the audit. Examples: a specific funnel worth measuring, an experiment worth running on a key flow, a cohort definition that would unlock churn prediction, a data warehouse join that would expose revenue-by-feature. One to two sentences each on what and why. Link to docs. ## Output rules - Plain markdown. H2 per section, H3 per sub-area. - Embed PostHog insights (trends, funnels, retention, etc.) inline where data benefits from visualization. - Include the full HogQL query under any non-trivial finding so the customer can re-run or customize it. Do NOT save these as named PostHog insights. - Bullets only, max 5 per section. Max 3 sentences per bullet. If more detail is needed, split into nested sub-bullets, not longer prose. - No markdown tables (notebooks do not render them). For comparisons, use bold-labeled bullets. - Use blank lines to separate sections. Do NOT use horizontal rule dividers (three hyphens in a row). - NO EM DASHES anywhere in the output. Em dashes (the long dash typographic character) and double-hyphen sequences used as dashes are both forbidden. Use commas, colons, parentheses, or full stops instead. This is critical: em dashes make writing read as AI-generated. - No "Step 1:" or "Phase N:" prefixes in headings. - No internal-to-PostHog framing. Do not write things like "PostHog adoption is 2 months old" or "the setup is sophisticated for an account this size." The customer knows their setup. Focus on what they should do, not commentary on what they have. - VERIFY before describing data. When a check might conflate two similar things (see Common pitfalls in the Audit section), confirm which one the query is actually returning before writing the finding. If unsure, say so explicitly rather than guessing. - HogQL specifics: `team_id` is a reserved keyword (alias to `team` instead); cast functions are HogQL-flavoured (`toInt(...)` not `toInt64(...)`); timestamps are UTC by default (be explicit about timezone if business hours matter). - Be concise everywhere. Cut every sentence that does not add information.
+</details>
+
 Lastly, if the customer is trending toward growth (usage, team expansion, increasing volume), it’s okay to mention pre-paid credits and the option of dedicated human support early. Framing it as “when you’re ready” gives them time to consider it and makes a future Sales handoff smoother.
 
 ### No response?
@@ -83,6 +100,8 @@ Tailor the email to their likely concerns:
 
 A small, human touch can help here! Use what’s publicly obvious or clearly relevant (their product category, their website messaging, their goals). If you genuinely relate (e.g., you’re learning a language and they build a language app), one sentence can be enough to build rapport. That’s also a great tip for the first outreach. 
 
+You can also draw inspiration from the [Customer Success team's tactics](https://posthog.com/handbook/cs-and-onboarding/engaging-unengaged-customers), such as flagging outdated SDKs.
+
 ## Preparing for the call
 
 **Start from a health check**
@@ -172,7 +191,7 @@ Follow-up with: Now go look at their business and domain. What should they be do
 - **Start with a quick discovery (3–5 minutes)**.  What they shared in the booking form may not reflect today’s priorities or the goals of everyone on the call. Confirm what outcome they want by the end of the session.
 - **Have the relevant docs ready**. If you can anticipate the topic of the session, keep the key docs open so you can screen-share them quickly.
 - **Show, don’t tell. Build things live**. If you discuss funnels, dashboards, cohorts, or flags, create one. Save it so the customer can revisit it later.
--**Connect features**. Show how features compound and check [this Handbook page](https://posthog.com/handbook/growth/cross-selling/cross-sell-motions#bundle-features) for inspiration:
+- **Connect features**. Show how features compound and check [this Handbook page](https://posthog.com/handbook/growth/cross-selling/cross-sell-motions#bundle-features) for inspiration:
   - Funnels → drop-off → jump into Session Replay to understand it better and create a cohort
   - Error tracking → watch related replays
   - Experiments → measurable impact → rolling out the winning variant
@@ -193,4 +212,5 @@ Follow-up with: Now go look at their business and domain. What should they be do
 - Loop in everybody. If some folks couldn’t attend, include them anyway so they can catch up async.
 - Summarize the call and send resources. Include some extra resources if you feel it would be beneficial as well. For example, our [YouTube playlist](https://www.youtube.com/playlist?list=PLnOY1RYHjDfzBX5wsSUHwLj91xuGnH5Ci%C2%A0) is great!
 - If relevant, give them one quick win. Encourage a small task they can do immediately after the call to lock in value and reinforce learning.
+- If you feel you have built a strong relationship, use your champion to introduce you to other teams that might be interested in PostHog and might be willing to jump on the call to be shown around.
 - Share any feedback or feature requests with the relevant product team. Their responsiveness can help you deliver some customer happiness! It's always great to be able to send a GitHub link to follow in your email.