From de0fcd8871fce254feda635eac74debc844ffde6 Mon Sep 17 00:00:00 2001 From: Arthur Moreira de Deus Date: Sun, 12 Apr 2026 14:32:10 -0300 Subject: [PATCH 1/4] fix: Add tenet to preserve unrelated existing code --- transformation-config/skills/revenue-analytics/description.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/transformation-config/skills/revenue-analytics/description.md b/transformation-config/skills/revenue-analytics/description.md index fb9b8d9a..2c2a2fb2 100644 --- a/transformation-config/skills/revenue-analytics/description.md +++ b/transformation-config/skills/revenue-analytics/description.md @@ -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: @@ -60,6 +62,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 From 2e85bbc7236cbc6167905e301c2bc2075354b5dd Mon Sep 17 00:00:00 2001 From: Arthur Moreira de Deus Date: Sun, 12 Apr 2026 14:42:07 -0300 Subject: [PATCH 2/4] fix: Callout not to consider stripe's checkout session client_reference_id as posthog distinct_id --- transformation-config/skills/revenue-analytics/description.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/transformation-config/skills/revenue-analytics/description.md b/transformation-config/skills/revenue-analytics/description.md index 2c2a2fb2..38e4e105 100644 --- a/transformation-config/skills/revenue-analytics/description.md +++ b/transformation-config/skills/revenue-analytics/description.md @@ -34,6 +34,8 @@ 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. + ## What to modify ### Step 1: Add metadata to Stripe Customer creation From 4142e84c186d8e4af5a262937f91526c45cdc80b Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Tue, 14 Apr 2026 11:25:06 -0400 Subject: [PATCH 3/4] Abort --- llm-prompts/basic-integration/1.0-begin.md | 4 ++++ .../skills/revenue-analytics/description.md | 12 +++++++++++- 2 files changed, 15 insertions(+), 1 deletion(-) 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 38e4e105..90037e7a 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. 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. @@ -36,6 +36,8 @@ Once you know WHAT value is the distinct_id, determine HOW to access that same v **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 @@ -46,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`. @@ -91,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} From 5ab96f59465389d96ae60b4df182d057b98bbf69 Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Tue, 14 Apr 2026 14:24:59 -0400 Subject: [PATCH 4/4] if not possible, leave placeholder --- transformation-config/skills/revenue-analytics/description.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/transformation-config/skills/revenue-analytics/description.md b/transformation-config/skills/revenue-analytics/description.md index 90037e7a..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. Bring in the exact same identifier as used in the PostHog integrations. +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.