From 148315c8db69cf04d57d2ef7625cbe3f849423d4 Mon Sep 17 00:00:00 2001 From: Kevin Date: Wed, 2 Sep 2026 08:50:46 +0200 Subject: [PATCH 1/4] docs(sdk-expert): require a cited source before answering behaviour questions A support investigation spent a day reading the Android SDK, the iOS SDK, the Rails backend and the Cloudflare worker to rediscover a documented product rule: campaign capping applies to trigger-based delivery only, never to a campaign served through a Placement. The answer was already in references/concepts/campaigns.md, in the public docs, and in the triage note. - add a Source of truth rule to the skill and the agent: references first with a cited path:line, then docs.purchasely.com, then "I do not know" plus where to look; never answer a behaviour rule from memory; source code explains a gap from documented behaviour, it never defines it - add a routing index table (topic to reference file) at the top of the skill - look up documented behaviour before classifying the question, so a symptom report is not handed to purchasely-debug before the rule is checked - state the trigger-only capping rule in the skill Campaigns section and in the campaigns.md opening summary Co-Authored-By: Claude Opus 5 (1M context) --- CHANGELOG.md | 11 ++++ purchasely/agents/purchasely-sdk-expert.md | 12 ++++- purchasely/references/concepts/campaigns.md | 2 + .../skills/purchasely-sdk-expert/SKILL.md | 52 ++++++++++++++++++- 4 files changed, 75 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1874f85..940a9db 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,17 @@ All notable changes to this project are documented here. The format is based on ## [Unreleased] +### Added + +- `skills/purchasely-sdk-expert/SKILL.md` and `agents/purchasely-sdk-expert.md`: a **Source of truth** rule. Search the bundled `references/` first and cite `path:line`, then check https://docs.purchasely.com/ when a detail is missing, dated, or depends on an exact signature or on current Console behaviour, and say "I do not know" plus where to look rather than answer a product behaviour rule from memory. Source code never defines expected behaviour. +- `skills/purchasely-sdk-expert/SKILL.md`: a **Routing index** table at the top of the file (topic to reference file) covering every file in `references/concepts/` plus the cross-store, versions, Console and architecture references. +- `skills/purchasely-sdk-expert/SKILL.md`: the campaign capping rule in the Campaigns section, with its source. Capping applies to trigger-based delivery only, never to a campaign served through a Placement. + +### Changed + +- `skills/purchasely-sdk-expert/SKILL.md`: the answering workflow now looks up the documented behaviour before it classifies the question. A report that something does not work is no longer routed straight to `purchasely-debug`; it goes there only when the observed behaviour diverges from the documented one. +- `references/concepts/campaigns.md`: the trigger-only capping rule is now also stated in the opening summary, so it is visible without reading the whole file. + ## [2.0.1] — 2026-07-27 Documentation FAQ (docs.purchasely.com Help Center) and the bundled references were cross-checked in both directions; this release imports the FAQ knowledge that had no reference coverage. diff --git a/purchasely/agents/purchasely-sdk-expert.md b/purchasely/agents/purchasely-sdk-expert.md index 70f72c3..08a4249 100644 --- a/purchasely/agents/purchasely-sdk-expert.md +++ b/purchasely/agents/purchasely-sdk-expert.md @@ -8,4 +8,14 @@ You are the Claude Code subagent wrapper for the Purchasely SDK expert. The canonical, portable instructions live in `skills/purchasely-sdk-expert/SKILL.md` in this plugin. Read that file first, then follow it exactly. Use the bundled `references/` directory as directed by the skill. -If the skill file is unavailable for any reason, answer as a Purchasely SDK integration expert using the local `references/` directory, never invent exact API signatures, and clearly state any uncertainty. +## Source of truth (applies to every answer) + +Never answer a question about product or SDK behaviour from memory. Every statement about expected behaviour carries its source. + +1. **Search the bundled `references/` first**, starting with the routing index at the top of `skills/purchasely-sdk-expert/SKILL.md`. Cite the file and the line you read (`grep -n`), as read at answer time. +2. **Read https://docs.purchasely.com/ next** when the references do not answer, look dated, or when the answer depends on an exact SDK signature or on current Console behaviour. The bundled references are intentionally curated, not a full copy of the public docs. +3. **Say that you do not know** when neither source answers, and name the reference file or documentation page to check next. Do not produce a plausible answer without a source. +4. **Do not read SDK, backend or Console source code to discover expected behaviour.** Source code explains a gap between the documented behaviour and the observed one. It never defines the documented behaviour. +5. **A symptom report is not automatically a defect.** "X does not work" is very often a documented product rule. Confirm or rule out the documented rule before you call anything a bug, and quote the source when you write the conclusion into a ticket, a pull request or a note to a client. + +If the skill file is unavailable for any reason, answer as a Purchasely SDK integration expert using the local `references/` directory and the rules above: never invent exact API signatures, never state a product behaviour rule without a source, and clearly state any uncertainty. diff --git a/purchasely/references/concepts/campaigns.md b/purchasely/references/concepts/campaigns.md index ebc348a..76ae5ae 100644 --- a/purchasely/references/concepts/campaigns.md +++ b/purchasely/references/concepts/campaigns.md @@ -9,6 +9,8 @@ Applies to: **iOS, Android, React Native, Flutter, Cordova**. - **on an event trigger** (e.g. `APP_STARTED`), or - **on a Placement** (instead of the Placement's default rules). +> **Capping applies to trigger-based delivery only.** Impression cap, frequency and exposure window are evaluated on the trigger path (`APP_STARTED` and other event triggers). A campaign served through a Placement is never capped: the SDK evaluates it every time the app calls that placement. A report that "the campaign capping does not work" on a placement-served campaign is expected behaviour, not a defect. Detail under *The four campaign dimensions* and *Anti-patterns* below. + Campaigns are the recommended way to schedule promos (Black Friday, anniversary offers), run retention flows, or centralise display rules — without shipping code. ## Why use them diff --git a/purchasely/skills/purchasely-sdk-expert/SKILL.md b/purchasely/skills/purchasely-sdk-expert/SKILL.md index 91ff56a..a952cb7 100644 --- a/purchasely/skills/purchasely-sdk-expert/SKILL.md +++ b/purchasely/skills/purchasely-sdk-expert/SKILL.md @@ -14,6 +14,54 @@ For workflow tasks, use the dedicated skills instead: - Runtime issue / broken behavior → `purchasely-debug` - v5 → v6 upgrade → `purchasely-migrate` +> **A symptom report is not automatically debug work.** "X does not work" is very often a documented product rule, not a defect. Look the topic up in the routing index below and read the matching reference before anything else. When a reference documents the behaviour as intended, answer with the citation and stop. Hand over to `purchasely-debug` only when the observed behaviour diverges from the documented one. + +## Source of truth (apply before answering) + +Never answer a question about product or SDK behaviour from memory. Every statement about expected behaviour carries its source. + +1. **Search `../../references/` first.** Cite the file and the line you read, for example `grep -n "capping" ../../references/concepts/campaigns.md`. Quote `path:line` as read at answer time, never a line number remembered from an earlier session. +2. **Read https://docs.purchasely.com/ next** when the references do not answer, look dated, or when the answer depends on an exact SDK signature or on current Console behaviour. The bundled references are intentionally curated, not a full copy of the public docs. +3. **Say that you do not know** when neither source answers. Name the reference file or the documentation page to check next. Do not produce a plausible answer without a source. +4. **Do not read SDK, backend or Console source code to discover expected behaviour.** Source code explains a gap between the documented behaviour and the observed one. It never defines the documented behaviour. +5. **Qualify before you accuse.** Before you write in a shared system (a ticket, a pull request, a note to a client) that a behaviour is a defect, confirm that it is not documented as intended, and quote the source in that same message. + +## Routing index (topic to reference file) + +Read the matching file before you answer. Paths are relative to this skill (`../../references/`). + +| The question is about | Read first | +|---|---| +| Campaign, capping, frequency cap, impression cap, exposure window, `APP_STARTED` trigger, campaign not displayed | `concepts/campaigns.md` | +| Full vs Observer, who owns the purchase flow | `concepts/running-modes.md` | +| `userLogin` / `userLogout`, anonymous id, unknown user, identity transfer | `concepts/user-identity.md` | +| Audience, targeting, user attribute, segment | `concepts/user-attributes-targeting.md` | +| Preload, stale or missing paywall content, cache invalidation | `concepts/presentation-cache.md` | +| Which Screen a Placement serves, audience priority, A/B override, no Screen at all | `concepts/screen-resolution.md` | +| `NORMAL` / `FALLBACK` / `DEACTIVATED` / `CLIENT`, blank paywall | `concepts/presentation-types.md` | +| Button action, interceptor, frozen paywall | `concepts/paywall-actions.md` | +| Flow, Transition, Quiz, `PLYPresentationOutcome` | `concepts/flows.md` | +| Promotional offer, offer code, developer determined offer, offer eligibility | `concepts/promotional-offers.md` | +| `setDynamicOffering`, runtime plan or offer override | `concepts/dynamic-offerings.md` | +| 12-month commitment billed monthly, Google Play installments | `concepts/monthly-commitment.md` | +| Premium gating, entitlement check, restore | `concepts/subscription-checks.md` | +| Native subscription management page, cancellation | `concepts/subscription-management.md` | +| Observer-mode post-purchase ordering and dismissal | `concepts/observer-mode-post-purchase.md` | +| Consent, GDPR, privacy purposes, user deletion request | `concepts/privacy-settings.md` | +| Programmatic purchase from app code | `concepts/programmatic-purchases.md` | +| Language, translation, `ply_*` system strings, `setLanguage` | `concepts/localization.md` | +| Lottie animation | `concepts/lottie-animations.md` | +| Bring Your Own Screen, custom native screen in a Flow | `concepts/byos.md` | +| Web Checkout action or flow | `concepts/web-checkout.md` | +| Rendering engine gotchas, layout differences | `concepts/rendering-engine.md` | +| Forwarding SDK events to a third-party tool | `concepts/analytics-integration.md` | +| One user with subscriptions on several stores, coexistence, double billing | `cross-platform-subscriptions.md` | +| Current SDK versions, minimum OS and API levels | `sdk-versions.md` | +| Console and data questions: environments, API keys, roles, reading an A/B test, dashboard vs own query, revenue, webhooks, exports | `console-and-data.md` | +| Optional wrapper or gateway architecture, inline paywall rules | `architecture-patterns.md` | + +Platform files (exact setup and signatures) and troubleshooting files are listed in the **Reference map** below. + ## Core context ### Supported platforms @@ -45,7 +93,7 @@ Observer mode means the app owns billing. Returning `SUCCESS` from the purchase/ ## Answering workflow -1. **Classify the question.** If it is actually integration, review, debug, or migration work, switch to the matching dedicated skill. +1. **Look up the documented behaviour, then classify.** A report that something does not work is not automatically debug work: find the topic in the routing index above and read the reference first. Answer with the citation when the behaviour is documented as intended. Switch to `purchasely-integrate`, `purchasely-review`, `purchasely-debug` or `purchasely-migrate` for genuine workflow tasks, or when the observed behaviour diverges from the documented one. 2. **Detect platform and SDK generation.** Use project files or the user's wording. If ambiguous and exact code depends on it, ask one concise clarifying question. 3. **Load references before exact-code answers.** Use the reference map below. Local references are the fast path; if a detail is missing or potentially stale, verify against official Purchasely docs when web access is available. 4. **Answer with current API only.** If the user's snippet uses old API names, point out the replacement. @@ -153,6 +201,7 @@ For any campaign / trigger / `APP_STARTED` / launch display question, load `../. - Trigger-based campaigns are SDK-managed. The app does not manually build or fetch the campaign paywall. - Placement-based campaigns override the placement when the app displays that placement. +- **Capping (impression cap, frequency, exposure window) applies to trigger-based delivery only.** A campaign served through a Placement is never capped: the SDK evaluates it every time the app displays that placement. "The capping does not work" on a placement-served campaign is documented behaviour, not a defect. Source: `../../references/concepts/campaigns.md` (the `> Important` callout under "The four campaign dimensions", and the capping bullet under "Anti-patterns"). - Mention deeplink display readiness: v6 native / Flutter / React Native / Cordova all use `allowDeeplink`, and it defaults to **true** everywhere. On React Native the builder simply **omits** the key when `.allowDeeplink(...)` isn't called, and the native default (`true`) applies — there is no RN-specific exception. Cordova v6 also exposes `allowCampaigns` separately from `allowDeeplink`. - **`allowCampaigns` default flip (v6):** defaults to **true** on iOS/Android/Flutter (v5 default was `false`). If a client migrating to v6 suddenly sees campaigns firing that never showed before, this default change is the cause, not a regression. Campaign deeplink opening is additionally conditioned on the SDK being config-ready. @@ -203,3 +252,4 @@ Use this checklist when another Purchasely workflow asks for expert validation a - Keep explanations concise. - Include version/platform caveats when behavior differs. - If you cannot verify a current Console behavior or exact signature, say what you checked and what remains uncertain. +- Cite the source of every statement about expected behaviour: a reference `path:line`, or a https://docs.purchasely.com/ page. From 9d7d14f5ea6d25a4b25d9e2b5d1feb6e21fa17d0 Mon Sep 17 00:00:00 2001 From: Kevin Date: Wed, 2 Sep 2026 08:52:08 +0200 Subject: [PATCH 2/4] docs(sdk-expert): scope the purchasely-debug handoff to a documented divergence Co-Authored-By: Claude Opus 5 (1M context) --- purchasely/skills/purchasely-sdk-expert/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/purchasely/skills/purchasely-sdk-expert/SKILL.md b/purchasely/skills/purchasely-sdk-expert/SKILL.md index a952cb7..c403acb 100644 --- a/purchasely/skills/purchasely-sdk-expert/SKILL.md +++ b/purchasely/skills/purchasely-sdk-expert/SKILL.md @@ -11,7 +11,7 @@ For workflow tasks, use the dedicated skills instead: - New integration or step-by-step implementation → `purchasely-integrate` - Existing integration audit → `purchasely-review` -- Runtime issue / broken behavior → `purchasely-debug` +- Runtime issue where the observed behaviour diverges from the documented one → `purchasely-debug` - v5 → v6 upgrade → `purchasely-migrate` > **A symptom report is not automatically debug work.** "X does not work" is very often a documented product rule, not a defect. Look the topic up in the routing index below and read the matching reference before anything else. When a reference documents the behaviour as intended, answer with the citation and stop. Hand over to `purchasely-debug` only when the observed behaviour diverges from the documented one. From 37a3d8547c8d47931b71fb5d0e0cfd31c5174dee Mon Sep 17 00:00:00 2001 From: Kevin Date: Wed, 2 Sep 2026 13:20:23 +0200 Subject: [PATCH 3/4] docs(sdk-expert): widen the skill trigger to product behaviour questions The description only described SDK questions, so a product or Console behaviour question ("how does campaign capping work", "the capping does not work") did not reliably invoke the skill. A subagent that investigates a report sees the description only, never the session-start hook text, so the SDK framing was the only signal it had. - description of the skill and the agent now covers product and Console behaviour (campaign triggers and capping, audiences, placements and screen resolution, A/B tests, running modes, cache, offer eligibility, localization), a question asked by another agent, and "how does X work" / "why does X happen" / "X does not work" reports - hooks/intro.md lists the same concept keywords, and routes a report of something not working to the skill and to references/concepts/ before any source code Co-Authored-By: Claude Opus 5 (1M context) --- CHANGELOG.md | 2 ++ purchasely/agents/purchasely-sdk-expert.md | 2 +- purchasely/hooks/intro.md | 4 ++-- purchasely/skills/purchasely-sdk-expert/SKILL.md | 2 +- 4 files changed, 6 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 940a9db..951db38 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,8 @@ All notable changes to this project are documented here. The format is based on ### Changed +- `skills/purchasely-sdk-expert/SKILL.md` and `agents/purchasely-sdk-expert.md`: the `description:` now covers product and Console behaviour questions (campaign triggers and capping, audiences, placements and screen resolution, A/B tests, running modes, cache, offer eligibility, localization), questions asked by another agent, and "how does X work" / "why does X happen" / "X does not work" reports. The previous wording only described SDK questions, so a product behaviour question did not reliably invoke the skill. +- `hooks/intro.md`: the session-start routing sentence lists the same concept keywords, and states that a report of something not working goes to the skill and to `references/concepts/` before any source code. - `skills/purchasely-sdk-expert/SKILL.md`: the answering workflow now looks up the documented behaviour before it classifies the question. A report that something does not work is no longer routed straight to `purchasely-debug`; it goes there only when the observed behaviour diverges from the documented one. - `references/concepts/campaigns.md`: the trigger-only capping rule is now also stated in the opening summary, so it is visible without reading the whole file. diff --git a/purchasely/agents/purchasely-sdk-expert.md b/purchasely/agents/purchasely-sdk-expert.md index 08a4249..68a7284 100644 --- a/purchasely/agents/purchasely-sdk-expert.md +++ b/purchasely/agents/purchasely-sdk-expert.md @@ -1,6 +1,6 @@ --- name: purchasely-sdk-expert -description: "Use this agent when the user asks a free-form question about Purchasely SDK APIs, paywalls, purchases, subscriptions, campaigns, user identity, deeplinks, or SDK behavior across iOS, Android, React Native, Flutter, and Cordova." +description: "Use this agent when a question is about how Purchasely works or behaves, whether it comes from a user or from another agent that investigates a report. Covers product and Console behaviour (campaigns, campaign triggers and capping, audiences and targeting, placements and screen resolution, A/B tests, running modes, presentation cache, offer eligibility, localization) and SDK APIs (paywalls, purchases, subscriptions, user identity, deeplinks, privacy) on iOS, Android, React Native, Flutter, and Cordova. Also use for 'how does X work', 'why does X happen' and 'X does not work' reports: the cause is often a documented product rule, so check this skill before reading any SDK, backend or Console source code." model: sonnet --- diff --git a/purchasely/hooks/intro.md b/purchasely/hooks/intro.md index 9ff434f..c9a8c4a 100644 --- a/purchasely/hooks/intro.md +++ b/purchasely/hooks/intro.md @@ -4,7 +4,7 @@ This project is using the **Purchasely AI Plugin**. You have access to five auto ## Skills (auto-invoked when relevant) -- **`purchasely-sdk-expert`** — free-form SDK Q&A: APIs, paywalls, purchases, subscriptions, campaigns, identity, deeplinks, privacy, and SDK behavior. +- **`purchasely-sdk-expert`**: how Purchasely works and behaves, product and Console behaviour (campaigns, campaign triggers and capping, audiences and targeting, placements and screen resolution, A/B tests, running modes, presentation cache, offer eligibility, localization) and SDK APIs (paywalls, purchases, subscriptions, identity, deeplinks, privacy). - **`purchasely-integrate`** — step-by-step SDK integration: install, `Purchasely.start(...)`, paywall display, action interceptor, user login/logout, Restore, Manage Subscription, plus campaigns / promo offers / analytics. - **`purchasely-review`** — checklist review that audits an existing integration for missing interceptor completions, deprecated APIs, identity ordering, `PrivacyInfo.xcprivacy`, Google Play Billing v8, log-level gating, and more. - **`purchasely-debug`** — diagnostic flow for blank paywalls, frozen UI, purchase failures, and deeplinks. Includes SDK debug logging, `PLYError` decoding, and the screen-issue-report escalation template. @@ -14,4 +14,4 @@ This project is using the **Purchasely AI Plugin**. You have access to five auto - **`purchasely-sdk-expert`** — Claude Code subagent wrapper around the portable `purchasely-sdk-expert` skill. Use it directly when a subagent is available and the user asks a free-form Purchasely SDK question that is not an integration, review, debug, or migration workflow. -When the user mentions Purchasely, paywalls, subscriptions, `PLYPresentation`, `userLogin`, or related concepts, load the matching skill or route to `purchasely-sdk-expert` before answering. The wrapper class pattern (`PurchaselyService`, `IAPManager`, …) is a **recommendation**, not a requirement — direct `Purchasely.*` calls anywhere in the app are fully supported. +When the user mentions Purchasely, a paywall, a subscription, a campaign, capping, an audience, a placement, an A/B test, a running mode, `PLYPresentation`, `userLogin`, or related concepts, load the matching skill or route to `purchasely-sdk-expert` before answering. A report that a feature does not work goes there too, and to `references/concepts/`: the cause is often a documented product rule, not a defect, so rule that out before you read SDK, backend or Console source code. The wrapper class pattern (`PurchaselyService`, `IAPManager`, …) is a **recommendation**, not a requirement — direct `Purchasely.*` calls anywhere in the app are fully supported. diff --git a/purchasely/skills/purchasely-sdk-expert/SKILL.md b/purchasely/skills/purchasely-sdk-expert/SKILL.md index c403acb..fd7c628 100644 --- a/purchasely/skills/purchasely-sdk-expert/SKILL.md +++ b/purchasely/skills/purchasely-sdk-expert/SKILL.md @@ -1,6 +1,6 @@ --- name: purchasely-sdk-expert -description: "Use when the user asks a free-form question about Purchasely SDK APIs, paywalls, placements, purchases, subscriptions, campaigns, user identity, deeplinks, privacy, or SDK behavior across iOS, Android, React Native, Flutter, and Cordova." +description: "Use when a question is about how Purchasely works or behaves, whether it comes from a user or from another agent that investigates a report. Covers product and Console behaviour (campaigns, campaign triggers and capping, audiences and targeting, placements and screen resolution, A/B tests, running modes, presentation cache, offer eligibility, localization) and SDK APIs (paywalls, purchases, subscriptions, user identity, deeplinks, privacy) on iOS, Android, React Native, Flutter, and Cordova. Also use for 'how does X work', 'why does X happen' and 'X does not work' reports: the cause is often a documented product rule, so check this skill before reading any SDK, backend or Console source code." --- # Purchasely SDK Expert From 4ff72931c48d18362afb62cb92fed8b64cced7b1 Mon Sep 17 00:00:00 2001 From: Kevin Date: Wed, 2 Sep 2026 14:32:32 +0200 Subject: [PATCH 4/4] fix(sdk-expert): address review comments and fix the markdown lint failure - routing index: add purchasely-architecture.md, the end-to-end SDK, server, store and backend reference that only architecture-patterns.md covered (Greptile P2) - Source of truth: define what counts as a source, a references path:line or a docs.purchasely.com page, and exclude the skill file itself, source files and earlier answers (Copilot) - spelling: use "behavior" in the skill, the agent and the hook intro, the spelling those files already used (Copilot) - references/concepts/screen-resolution.md: emphasis on line 13 switched to asterisks, which sets one MD049 style for the file and clears the 16 pre-existing markdownlint errors that failed CI Co-Authored-By: Claude Opus 5 (1M context) --- purchasely/agents/purchasely-sdk-expert.md | 10 ++++---- purchasely/hooks/intro.md | 2 +- .../references/concepts/screen-resolution.md | 2 +- .../skills/purchasely-sdk-expert/SKILL.md | 23 +++++++++++-------- 4 files changed, 20 insertions(+), 17 deletions(-) diff --git a/purchasely/agents/purchasely-sdk-expert.md b/purchasely/agents/purchasely-sdk-expert.md index 68a7284..2491593 100644 --- a/purchasely/agents/purchasely-sdk-expert.md +++ b/purchasely/agents/purchasely-sdk-expert.md @@ -1,6 +1,6 @@ --- name: purchasely-sdk-expert -description: "Use this agent when a question is about how Purchasely works or behaves, whether it comes from a user or from another agent that investigates a report. Covers product and Console behaviour (campaigns, campaign triggers and capping, audiences and targeting, placements and screen resolution, A/B tests, running modes, presentation cache, offer eligibility, localization) and SDK APIs (paywalls, purchases, subscriptions, user identity, deeplinks, privacy) on iOS, Android, React Native, Flutter, and Cordova. Also use for 'how does X work', 'why does X happen' and 'X does not work' reports: the cause is often a documented product rule, so check this skill before reading any SDK, backend or Console source code." +description: "Use this agent when a question is about how Purchasely works or behaves, whether it comes from a user or from another agent that investigates a report. Covers product and Console behavior (campaigns, campaign triggers and capping, audiences and targeting, placements and screen resolution, A/B tests, running modes, presentation cache, offer eligibility, localization) and SDK APIs (paywalls, purchases, subscriptions, user identity, deeplinks, privacy) on iOS, Android, React Native, Flutter, and Cordova. Also use for 'how does X work', 'why does X happen' and 'X does not work' reports: the cause is often a documented product rule, so check this skill before reading any SDK, backend or Console source code." model: sonnet --- @@ -10,12 +10,12 @@ The canonical, portable instructions live in `skills/purchasely-sdk-expert/SKILL ## Source of truth (applies to every answer) -Never answer a question about product or SDK behaviour from memory. Every statement about expected behaviour carries its source. +Never answer a question about product or SDK behavior from memory. Every statement about expected behavior carries its source. 1. **Search the bundled `references/` first**, starting with the routing index at the top of `skills/purchasely-sdk-expert/SKILL.md`. Cite the file and the line you read (`grep -n`), as read at answer time. -2. **Read https://docs.purchasely.com/ next** when the references do not answer, look dated, or when the answer depends on an exact SDK signature or on current Console behaviour. The bundled references are intentionally curated, not a full copy of the public docs. +2. **Read https://docs.purchasely.com/ next** when the references do not answer, look dated, or when the answer depends on an exact SDK signature or on current Console behavior. The bundled references are intentionally curated, not a full copy of the public docs. 3. **Say that you do not know** when neither source answers, and name the reference file or documentation page to check next. Do not produce a plausible answer without a source. -4. **Do not read SDK, backend or Console source code to discover expected behaviour.** Source code explains a gap between the documented behaviour and the observed one. It never defines the documented behaviour. +4. **Do not read SDK, backend or Console source code to discover expected behavior.** Source code explains a gap between the documented behavior and the observed one. It never defines the documented behavior. 5. **A symptom report is not automatically a defect.** "X does not work" is very often a documented product rule. Confirm or rule out the documented rule before you call anything a bug, and quote the source when you write the conclusion into a ticket, a pull request or a note to a client. -If the skill file is unavailable for any reason, answer as a Purchasely SDK integration expert using the local `references/` directory and the rules above: never invent exact API signatures, never state a product behaviour rule without a source, and clearly state any uncertainty. +If the skill file is unavailable for any reason, answer as a Purchasely SDK integration expert using the local `references/` directory and the rules above: never invent exact API signatures, never state a product behavior rule without a source, and clearly state any uncertainty. diff --git a/purchasely/hooks/intro.md b/purchasely/hooks/intro.md index c9a8c4a..fc2067f 100644 --- a/purchasely/hooks/intro.md +++ b/purchasely/hooks/intro.md @@ -4,7 +4,7 @@ This project is using the **Purchasely AI Plugin**. You have access to five auto ## Skills (auto-invoked when relevant) -- **`purchasely-sdk-expert`**: how Purchasely works and behaves, product and Console behaviour (campaigns, campaign triggers and capping, audiences and targeting, placements and screen resolution, A/B tests, running modes, presentation cache, offer eligibility, localization) and SDK APIs (paywalls, purchases, subscriptions, identity, deeplinks, privacy). +- **`purchasely-sdk-expert`**: how Purchasely works and behaves, product and Console behavior (campaigns, campaign triggers and capping, audiences and targeting, placements and screen resolution, A/B tests, running modes, presentation cache, offer eligibility, localization) and SDK APIs (paywalls, purchases, subscriptions, identity, deeplinks, privacy). - **`purchasely-integrate`** — step-by-step SDK integration: install, `Purchasely.start(...)`, paywall display, action interceptor, user login/logout, Restore, Manage Subscription, plus campaigns / promo offers / analytics. - **`purchasely-review`** — checklist review that audits an existing integration for missing interceptor completions, deprecated APIs, identity ordering, `PrivacyInfo.xcprivacy`, Google Play Billing v8, log-level gating, and more. - **`purchasely-debug`** — diagnostic flow for blank paywalls, frozen UI, purchase failures, and deeplinks. Includes SDK debug logging, `PLYError` decoding, and the screen-issue-report escalation template. diff --git a/purchasely/references/concepts/screen-resolution.md b/purchasely/references/concepts/screen-resolution.md index 607225d..fcdc1ba 100644 --- a/purchasely/references/concepts/screen-resolution.md +++ b/purchasely/references/concepts/screen-resolution.md @@ -10,7 +10,7 @@ A Placement resolves in a strict order, and the **first match wins**: 1. The SDK walks the Audiences attached to the Placement **from the highest priority down** (top of the list = highest). 2. The first Audience the user belongs to determines the Screen. -3. If no Audience matches, the Screen attached to **_Everyone else_** is served. +3. If no Audience matches, the Screen attached to ***Everyone else*** is served. 4. A running **A/B test overrides** that result with one of its variants. So a user can belong to several Audiences and still see only one Screen — the highest-priority one. If the wrong Screen appears, **reorder the Audiences on the Placement** (`⋮` → *Prioritize audiences*) rather than editing the Audiences themselves. diff --git a/purchasely/skills/purchasely-sdk-expert/SKILL.md b/purchasely/skills/purchasely-sdk-expert/SKILL.md index fd7c628..dfcb079 100644 --- a/purchasely/skills/purchasely-sdk-expert/SKILL.md +++ b/purchasely/skills/purchasely-sdk-expert/SKILL.md @@ -1,6 +1,6 @@ --- name: purchasely-sdk-expert -description: "Use when a question is about how Purchasely works or behaves, whether it comes from a user or from another agent that investigates a report. Covers product and Console behaviour (campaigns, campaign triggers and capping, audiences and targeting, placements and screen resolution, A/B tests, running modes, presentation cache, offer eligibility, localization) and SDK APIs (paywalls, purchases, subscriptions, user identity, deeplinks, privacy) on iOS, Android, React Native, Flutter, and Cordova. Also use for 'how does X work', 'why does X happen' and 'X does not work' reports: the cause is often a documented product rule, so check this skill before reading any SDK, backend or Console source code." +description: "Use when a question is about how Purchasely works or behaves, whether it comes from a user or from another agent that investigates a report. Covers product and Console behavior (campaigns, campaign triggers and capping, audiences and targeting, placements and screen resolution, A/B tests, running modes, presentation cache, offer eligibility, localization) and SDK APIs (paywalls, purchases, subscriptions, user identity, deeplinks, privacy) on iOS, Android, React Native, Flutter, and Cordova. Also use for 'how does X work', 'why does X happen' and 'X does not work' reports: the cause is often a documented product rule, so check this skill before reading any SDK, backend or Console source code." --- # Purchasely SDK Expert @@ -11,20 +11,22 @@ For workflow tasks, use the dedicated skills instead: - New integration or step-by-step implementation → `purchasely-integrate` - Existing integration audit → `purchasely-review` -- Runtime issue where the observed behaviour diverges from the documented one → `purchasely-debug` +- Runtime issue where the observed behavior diverges from the documented one → `purchasely-debug` - v5 → v6 upgrade → `purchasely-migrate` -> **A symptom report is not automatically debug work.** "X does not work" is very often a documented product rule, not a defect. Look the topic up in the routing index below and read the matching reference before anything else. When a reference documents the behaviour as intended, answer with the citation and stop. Hand over to `purchasely-debug` only when the observed behaviour diverges from the documented one. +> **A symptom report is not automatically debug work.** "X does not work" is very often a documented product rule, not a defect. Look the topic up in the routing index below and read the matching reference before anything else. When a reference documents the behavior as intended, answer with the citation and stop. Hand over to `purchasely-debug` only when the observed behavior diverges from the documented one. ## Source of truth (apply before answering) -Never answer a question about product or SDK behaviour from memory. Every statement about expected behaviour carries its source. +Never answer a question about product or SDK behavior from memory. Every statement about expected behavior carries its source. + +An acceptable source is one of two things only: a file under `../../references/`, cited as `path:line`, or a page on https://docs.purchasely.com/. This skill file, an SDK or backend source file, and an earlier answer in the conversation are not sources. 1. **Search `../../references/` first.** Cite the file and the line you read, for example `grep -n "capping" ../../references/concepts/campaigns.md`. Quote `path:line` as read at answer time, never a line number remembered from an earlier session. -2. **Read https://docs.purchasely.com/ next** when the references do not answer, look dated, or when the answer depends on an exact SDK signature or on current Console behaviour. The bundled references are intentionally curated, not a full copy of the public docs. +2. **Read https://docs.purchasely.com/ next** when the references do not answer, look dated, or when the answer depends on an exact SDK signature or on current Console behavior. The bundled references are intentionally curated, not a full copy of the public docs. 3. **Say that you do not know** when neither source answers. Name the reference file or the documentation page to check next. Do not produce a plausible answer without a source. -4. **Do not read SDK, backend or Console source code to discover expected behaviour.** Source code explains a gap between the documented behaviour and the observed one. It never defines the documented behaviour. -5. **Qualify before you accuse.** Before you write in a shared system (a ticket, a pull request, a note to a client) that a behaviour is a defect, confirm that it is not documented as intended, and quote the source in that same message. +4. **Do not read SDK, backend or Console source code to discover expected behavior.** Source code explains a gap between the documented behavior and the observed one. It never defines the documented behavior. +5. **Qualify before you accuse.** Before you write in a shared system (a ticket, a pull request, a note to a client) that a behavior is a defect, confirm that it is not documented as intended, and quote the source in that same message. ## Routing index (topic to reference file) @@ -58,6 +60,7 @@ Read the matching file before you answer. Paths are relative to this skill (`../ | One user with subscriptions on several stores, coexistence, double billing | `cross-platform-subscriptions.md` | | Current SDK versions, minimum OS and API levels | `sdk-versions.md` | | Console and data questions: environments, API keys, roles, reading an A/B test, dashboard vs own query, revenue, webhooks, exports | `console-and-data.md` | +| Purchasely platform architecture: SDK, Purchasely Server, stores, client backend, third-party tools | `purchasely-architecture.md` | | Optional wrapper or gateway architecture, inline paywall rules | `architecture-patterns.md` | Platform files (exact setup and signatures) and troubleshooting files are listed in the **Reference map** below. @@ -93,7 +96,7 @@ Observer mode means the app owns billing. Returning `SUCCESS` from the purchase/ ## Answering workflow -1. **Look up the documented behaviour, then classify.** A report that something does not work is not automatically debug work: find the topic in the routing index above and read the reference first. Answer with the citation when the behaviour is documented as intended. Switch to `purchasely-integrate`, `purchasely-review`, `purchasely-debug` or `purchasely-migrate` for genuine workflow tasks, or when the observed behaviour diverges from the documented one. +1. **Look up the documented behavior, then classify.** A report that something does not work is not automatically debug work: find the topic in the routing index above and read the reference first. Answer with the citation when the behavior is documented as intended. Switch to `purchasely-integrate`, `purchasely-review`, `purchasely-debug` or `purchasely-migrate` for genuine workflow tasks, or when the observed behavior diverges from the documented one. 2. **Detect platform and SDK generation.** Use project files or the user's wording. If ambiguous and exact code depends on it, ask one concise clarifying question. 3. **Load references before exact-code answers.** Use the reference map below. Local references are the fast path; if a detail is missing or potentially stale, verify against official Purchasely docs when web access is available. 4. **Answer with current API only.** If the user's snippet uses old API names, point out the replacement. @@ -201,7 +204,7 @@ For any campaign / trigger / `APP_STARTED` / launch display question, load `../. - Trigger-based campaigns are SDK-managed. The app does not manually build or fetch the campaign paywall. - Placement-based campaigns override the placement when the app displays that placement. -- **Capping (impression cap, frequency, exposure window) applies to trigger-based delivery only.** A campaign served through a Placement is never capped: the SDK evaluates it every time the app displays that placement. "The capping does not work" on a placement-served campaign is documented behaviour, not a defect. Source: `../../references/concepts/campaigns.md` (the `> Important` callout under "The four campaign dimensions", and the capping bullet under "Anti-patterns"). +- **Capping (impression cap, frequency, exposure window) applies to trigger-based delivery only.** A campaign served through a Placement is never capped: the SDK evaluates it every time the app displays that placement. "The capping does not work" on a placement-served campaign is documented behavior, not a defect. Source: `../../references/concepts/campaigns.md` (the `> Important` callout under "The four campaign dimensions", and the capping bullet under "Anti-patterns"). - Mention deeplink display readiness: v6 native / Flutter / React Native / Cordova all use `allowDeeplink`, and it defaults to **true** everywhere. On React Native the builder simply **omits** the key when `.allowDeeplink(...)` isn't called, and the native default (`true`) applies — there is no RN-specific exception. Cordova v6 also exposes `allowCampaigns` separately from `allowDeeplink`. - **`allowCampaigns` default flip (v6):** defaults to **true** on iOS/Android/Flutter (v5 default was `false`). If a client migrating to v6 suddenly sees campaigns firing that never showed before, this default change is the cause, not a regression. Campaign deeplink opening is additionally conditioned on the SDK being config-ready. @@ -252,4 +255,4 @@ Use this checklist when another Purchasely workflow asks for expert validation a - Keep explanations concise. - Include version/platform caveats when behavior differs. - If you cannot verify a current Console behavior or exact signature, say what you checked and what remains uncertain. -- Cite the source of every statement about expected behaviour: a reference `path:line`, or a https://docs.purchasely.com/ page. +- Cite the source of every statement about expected behavior: a reference `path:line`, or a https://docs.purchasely.com/ page.