diff --git a/llm-prompts/basic-integration/1.0-begin.md b/llm-prompts/basic-integration/1.0-begin.md index 52285dd1..3433cfc2 100644 --- a/llm-prompts/basic-integration/1.0-begin.md +++ b/llm-prompts/basic-integration/1.0-begin.md @@ -36,3 +36,7 @@ Status to report in this phase: - Checking project structure - Verifying PostHog dependencies - Generating events based on project + +## Abort statuses + +If and only if the instructions have `[ABORT]` states specified, and you clearly match the conditions for an abort, emit the abort message. Do NOT attempt to exit or halt yourself — the wizard's middleware catches `[ABORT]` and terminates the run for you. \ No newline at end of file diff --git a/transformation-config/skills/revenue-analytics/description.md b/transformation-config/skills/revenue-analytics/description.md index fb9b8d9a..e8d4265b 100644 --- a/transformation-config/skills/revenue-analytics/description.md +++ b/transformation-config/skills/revenue-analytics/description.md @@ -12,7 +12,7 @@ Consult the PostHog revenue analytics documentation for the full setup guide, an Follow these tenets for every decision: -1. **Never fabricate the value.** If the PostHog distinct_id is not available in the current scope, do NOT substitute another identifier (Stripe customer ID, internal user ID, org ID, etc.). A wrong value is worse than no value — it corrupts metadata and blocks correct identification downstream. +1. **Never fabricate the value.** If the PostHog distinct_id is not available in the current scope, do NOT substitute another identifier (Stripe customer ID, internal user ID, org ID, etc.). A wrong value is worse than no value — it corrupts metadata and blocks correct identification downstream. Bring in the exact same identifier as used in the PostHog integrations. When this is not possible, use `"TODO_POSTHOG_DISTINCT_ID"` as a string placeholder and include this in the report. 2. **Thread the value, don't invent it.** If a function needs the distinct_id but doesn't have it, add it as an optional parameter propagated from a caller that does. If no caller in the chain has it, skip that call site entirely and leave a TODO comment. @@ -20,6 +20,8 @@ Follow these tenets for every decision: 4. **Follow existing Stripe abstraction patterns.** If the codebase wraps Stripe calls behind a utility/service layer, modify that layer. Don't call the Stripe API directly from business logic just to set metadata. +5. **Never refactor unrelated existing code.** The only parts of the codebase that should be changed are the ones immediately related to getting PostHog distinct_id into Stripe calls. All remaining code should be left as is regardless. + ## How to find the PostHog distinct_id Before writing any code, determine what this project uses as the PostHog distinct_id: @@ -32,6 +34,10 @@ Before writing any code, determine what this project uses as the PostHog distinc Once you know WHAT value is the distinct_id, determine HOW to access that same value at each Stripe call site. The variable name may differ between files — trace the data flow. +**Watch out!** Stripe's Checkout Sessions have a field called `client_reference_id`. This field **MAY NOT** be the same as PostHog distinct_id, so do not use it as a way to figure out what the distinc_id should be. + +If you could not find a valid PostHog distinct_id, emit `[ABORT] Could not find a PostHog distinct_id`. The wizard middleware catches `[ABORT]` and terminates the run — you do not need to halt yourself. + ## What to modify ### Step 1: Add metadata to Stripe Customer creation @@ -42,6 +48,8 @@ For each `Customer.create` call, add `posthog_person_distinct_id` to the `metada - If the distinct_id is not in scope, thread it as an optional parameter (Tenet 2). If no caller has it, skip this site with a TODO. - Check if the codebase wraps Stripe calls behind a utility layer — if so, modify the wrapper (Tenet 4). +If you could not find a valid Stripe integration, emit `[ABORT] Could not find a Stripe integration`. The wizard middleware catches `[ABORT]` and terminates the run — you do not need to halt yourself. + ### Step 2: Add metadata to Stripe payment/charge objects (REQUIRED) This step is **required**. The following Stripe objects support a `metadata` parameter: **Charge, PaymentIntent, Subscription, Invoice, Refund, Transfer**. Search the codebase for creation calls for any of these objects and add `posthog_person_distinct_id` to their `metadata`. @@ -60,6 +68,7 @@ If the project has a `checkout.session.completed` webhook handler and Stripe aut ### Step 3: Verify Read each modified file to verify: + - No syntax errors - Existing code logic is preserved - The metadata uses the correct distinct_id value — not a fabricated property @@ -86,6 +95,12 @@ Report progress with `[STATUS]` prefixed messages: - Verifying changes - Revenue analytics setup complete +## Abort statuses + +Report abort states with `[ABORT]` prefixed messages: +- Could not find PostHog distinct_id usage +- Could not find a Stripe integration + ## Framework guidelines {commandments}