@wix/agent-skills 1.12.0 → 1.14.0

package/skills/wix-manage/references/ecommerce/guardrail-discount-conflicts.md

@@ -1,118 +0,0 @@
----
-name: "Guardrail: Discount Conflicts"
-description: Validation rules for detecting and preventing discount stacking conflicts, coupon overlap, and unintended deep discounts before applying new promotions. Covers automatic discount rules, coupon interactions, and safe discount limits.
-layer: guardrail
-references:
-  - name: "Troubleshoot: Discount Not Applying"
-    path: ecommerce/troubleshoot-discount-not-applying.md
-    load: false
----
-# Guardrail: Discount Conflicts
-
-> **Related skills** (read with `ReadFullDocsArticle` if needed):
-> - [Troubleshoot: Discount Not Applying](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/troubleshoot-discount-not-applying)
-
-## When to use this guardrail
-
-Run these checks **before** creating or updating any discount — whether automatic discount rule or coupon. Discount conflicts are one of the most common merchant mistakes — overlapping discounts silently stack and give customers a much deeper discount than intended. This is especially dangerous when **automatic discounts and coupons interact**, since merchants often forget that both mechanisms apply simultaneously.
-
----
-
-## Check 1: Existing active discount rules on the same scope
-
-**Why:** Wix eCommerce stacks automatic discount rules. If a 20% catalog-wide discount and a 15% collection discount both apply to the same product, the customer may get both applied.
-
-**How to check:**
-
-1. Query all active discount rules:
-
-**Endpoint**: `POST https://www.wixapis.com/ecom/v1/discount-rules/query`
-
-**Request**:
-```json
-{
-  "query": {
-    "filter": {
-      "active": true
-    },
-    "paging": {
-      "limit": 100
-    }
-  }
-}
-```
-
-2. For each existing active rule, compare its scope against the new rule:
-   - If both target `CATALOG` scope: **conflict** — both apply to all products
-   - If new rule targets `CATALOG` and existing targets `COLLECTION`: **conflict** — catalog-wide includes that collection
-   - If both target the same `COLLECTION` ID: **conflict** — same products affected
-   - If both target the same `SPECIFIC_PRODUCTS` ID: **conflict** — same product
-
-3. If a conflict is found, warn the merchant:
-   > "There's already an active discount '{existingRuleName}' ({existingDiscount}%) that applies to the same products. Adding this new {newDiscount}% discount may stack, giving customers a combined discount. Would you like to deactivate the existing rule first, or proceed with both?"
-
----
-
-## Check 2: Discount percentage sanity
-
-**Why:** A discount above 50% is unusual and may indicate a typo (the merchant meant 15% not 50%). A discount of 100% makes the product free.
-
-**Rules:**
-- Discount > 50%: Warn — "This discount is {percentage}% off. Are you sure? This means a $100 product would sell for ${100 - percentage}."
-- Discount = 100%: Block unless explicitly confirmed — "This would make the product free. Please confirm this is intentional."
-- Discount > 100%: Block — "A discount cannot exceed 100%."
-
----
-
-## Check 3: Time overlap with existing promotions
-
-**Why:** Two promotions running simultaneously on overlapping products cause stacking during the overlap period.
-
-**How to check:**
-
-1. For the new rule's `activeTimeInfo` (start/end), check if any existing active rule has an overlapping time window on the same scope.
-2. Overlap exists when: `existingStart < newEnd AND existingEnd > newStart`
-3. If overlap found on the same scope: warn the merchant about the overlap period.
-
----
-
-## Check 4: Cross-mechanism stacking (Automatic + Coupon)
-
-**Why:** Automatic discounts and coupons stack with each other at checkout. A customer with a 20% coupon buying during a 20% automatic sale gets both applied — the effective discount is much deeper than either one alone. This is the most commonly overlooked stacking issue.
-
-**How to check:**
-
-1. If you are creating an **automatic discount**: Query active coupons that target overlapping products/collections.
-2. If you are creating a **coupon**: Query active automatic discount rules that target overlapping products/collections.
-3. If overlap found, warn the merchant with the combined impact:
-   > "You have an active {automatic discount / coupon} '{name}' ({X}% off) that applies to the same products. If you create this {coupon / automatic discount}, customers will get BOTH discounts — a combined effective discount of approximately {combined}%. Is this intentional?"
-
-**Key rule:** Only one coupon can be used per checkout, but automatic discounts have no such limit. The worst case is: multiple automatic discounts + one coupon all stacking on the same product.
-
----
-
-## Check 5: Minimum profit margin
-
-**Why:** Deep discounts on low-margin products can result in selling at a loss.
-
-**Rules:**
-- If the merchant has provided cost/margin information, verify that the discount doesn't reduce the price below cost
-- If no cost information is available, warn for discounts > 40% as a general safety threshold
-
----
-
-## Summary: Decision matrix
-
-| Scenario | Action |
-|---|---|
-| No conflicts found | Proceed with creating the discount |
-| Scope overlap with existing active automatic discount | Warn merchant, ask to deactivate existing or confirm stacking |
-| Cross-mechanism stacking (automatic + coupon on same scope) | Warn merchant with combined effective discount percentage |
-| Discount > 50% | Warn merchant, ask for confirmation |
-| Discount = 100% | Block unless explicitly confirmed |
-| Time overlap on same scope | Warn about overlap period |
-
-## References
-
-- [Discount Rules API (Automatic Discounts)](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/discounts/discount-rules/introduction)
-- [Coupons API](https://dev.wix.com/docs/api-reference/business-solutions/coupons/coupons/introduction)

package/skills/wix-manage/references/ecommerce/guardrail-margin-protection.md

@@ -1,88 +0,0 @@
----
-name: "Guardrail: Margin Protection"
-description: Safety constraints for discount percentages — global discount cap, minimum margin requirements, user override protocol, and percentage sanity checks.
-layer: guardrail
----
-# Guardrail: Margin Protection
-
-## When to apply
-
-Run before EVERY discount rule creation or update. Check both the new rule's discount AND the cumulative effect with existing active rules (stacking).
-
----
-
-## Constraint 1: Global discount cap
-
-The default maximum discount percentage (`discountMargin`) is **25%**.
-
-Any discount rule that exceeds this cap should be flagged before creation:
-
-> "This discount ({pct}%) exceeds the default cap of 25%. Proceeding only because you explicitly requested it."
-
-Respect the cap unless user input explicitly overrides it.
-
----
-
-## Constraint 2: Minimum margin requirement
-
-The default minimum margin percentage (`minMarginPct`) is **15%**.
-
-Never create a discount that would push the effective margin below 15% unless the user explicitly overrides this constraint.
-
-If cost data is available, calculate:
-- `effective_margin = (price - cost - discount_amount) / price × 100`
-- If `effective_margin < minMarginPct` → block and explain the margin impact.
-
----
-
-## Constraint 3: Percentage sanity checks
-
-| Discount value | Action |
-|---|---|
-| Discount > 50% | Warn — "This discount is {pct}% off. A $100 product would sell for ${100 - pct}. Are you sure?" |
-| Discount = 100% | Block unless explicitly confirmed — "This makes the product free." |
-| Discount > 100% | Block always — "A discount cannot exceed 100%." |
-
----
-
-## Constraint 4: User input override protocol (ABSOLUTE PRIORITY)
-
-User input overrides ALL constraints — margin caps, discount caps, naming conventions, percentage limits.
-
-**How it works:**
-
-- If the user says "50% discount" and the cap is 25%, honor 50%.
-- If the user says "set margin to 5%" and the minimum is 15%, honor 5%.
-- Document which constraints were overridden in reasoning so there is a clear audit trail.
-
-**Example reasoning output:**
-
-> "Creating a 50% discount as requested. Note: this overrides the default 25% discount cap. The effective margin on a product with 60% gross margin would drop to 10%, below the default 15% minimum margin threshold. Proceeding per explicit user instruction."
-
----
-
-## Constraint 5: Stacking cumulative check
-
-When creating a new discount, also check the cumulative effect with existing active rules:
-
-1. Query all active discount rules that overlap in scope with the new rule.
-2. Calculate the combined discount percentage (accounting for multiplicative stacking).
-3. If the combined discount exceeds the global cap or violates the minimum margin, warn the merchant:
-
-> "Combined with the existing '{existingRuleName}' ({existingPct}%), the total effective discount would be approximately {combinedPct}%. This exceeds the {cap}% cap / pushes margin below {minMarginPct}%."
-
----
-
-## Summary: Decision matrix
-
-| Scenario | Action |
-|---|---|
-| Discount ≤ 25% and margin ≥ 15% | Proceed |
-| Discount > 25% but ≤ 50%, no user override | Warn, ask for confirmation |
-| Discount > 25%, user explicitly requested | Proceed, document override |
-| Discount > 50% | Warn with dollar example, ask for confirmation |
-| Discount = 100% | Block unless explicitly confirmed |
-| Discount > 100% | Block always |
-| Combined stacking exceeds cap | Warn about cumulative effect |
-| Margin drops below 15%, no user override | Block, explain margin impact |
-| Margin drops below 15%, user override | Proceed, document override |

package/skills/wix-manage/references/ecommerce/guardrail-rate-pricing-sanity.md

@@ -1,108 +0,0 @@
----
-name: "Guardrail: Rate Pricing Sanity"
-description: Validates shipping rate pricing against AOV and catalog data. Flags excessive rates, per-item penalties, unreachable free shipping thresholds, and backup rate sticker shock.
-layer: guardrail
----
-# Guardrail: Rate Pricing Sanity
-
-## When to use
-
-Run these checks when evaluating existing shipping rates or before creating/updating shipping rate configurations. All thresholds are relative to the store's Average Order Value (AOV).
-
----
-
-## Check 1: Excessive shipping cost
-
-**Threshold**: Any rate `amount` > AOV x 0.15 (15%)
-
-**Why**: Shipping costs above 15% of order value are a top reason for cart abandonment. Customers who see disproportionately high shipping fees frequently abandon their carts.
-
-**Detection**:
-- For each shipping rate, compare `amount` against `AOV × 0.15`
-- If exceeded → flag:
-
-> "Shipping rate '{title}' charges ${amount}, which is {pct}% of your average order value (${AOV}). Shipping costs above 15% of order value are a top reason for cart abandonment."
-
----
-
-## Check 2: Per-item penalty (multiplyByQuantity)
-
-**Trigger**: `multiplyByQuantity: true` on any shipping rate
-
-**Why**: Per-item shipping charges penalize larger orders and discourage customers from adding more items to cart.
-
-**Detection**:
-- Find all rates with `multiplyByQuantity: true`
-- Calculate the impact for a typical multi-item order:
-
-> "Your '{title}' rate charges per item (${amount} x quantity). A 5-item order costs ${amount x 5}. Switch to a flat rate or tiered pricing to encourage larger orders."
-
----
-
-## Check 3: Free shipping threshold too high
-
-**Threshold**: Free shipping threshold > AOV x 2
-
-**Why**: If the free shipping minimum is more than double the average order, very few customers will ever qualify. The threshold should be achievable — close enough to the AOV to encourage customers to add one more item.
-
-**Detection**:
-- Compare free shipping `threshold` against `AOV × 2`
-- If exceeded → flag:
-
-> "Your free shipping threshold (${threshold}) is {X}x your average order (${AOV}). Most customers won't reach it. Lower to ${AOV x 1.2} to make it achievable and drive larger orders."
-
----
-
-## Check 4: Free shipping threshold too low
-
-**Threshold**: Free shipping threshold < AOV x 0.8
-
-**Why**: If the threshold is below the average order value, most customers already qualify for free shipping without adding anything to their cart. This provides no upsell incentive and may erode margins unnecessarily.
-
-**Detection**:
-- Compare free shipping `threshold` against `AOV × 0.8`
-- If below → flag:
-
-> "Your free shipping threshold (${threshold}) is below your average order value (${AOV}). Most customers already qualify, so this threshold isn't driving larger orders. Consider raising it to ${AOV x 1.2} to encourage add-on purchases."
-
----
-
-## Check 5: Backup rate sticker shock
-
-**Threshold**: `backupRate.amount` > effective AOV x 0.15
-
-**Why**: Backup rates apply when the primary carrier can't fulfill (e.g., remote address, service outage). If the backup rate is dramatically higher than normal shipping, customers experience sticker shock at checkout.
-
-**Detection**:
-- For each carrier's `backupRate`, compare `amount` against `effective_aov × 0.15`
-- If exceeded → flag:
-
-> "Backup rate of ${amount} is {pct}% of your average order value. When triggered, this will surprise customers with unexpectedly high shipping. Set the backup rate to 5-10% of average order value (${effective_aov x 0.05} - ${effective_aov x 0.10})."
-
----
-
-## Check 6: Hidden surcharges
-
-**Threshold**: Total `additionalCharges` across all carriers > AOV x 0.10
-
-**Why**: Carrier surcharges (fuel, residential delivery, handling fees) add up. If the total surcharge burden exceeds 10% of the order value, it may negate the perceived value of the base shipping rate.
-
-**Detection**:
-- Sum all `additionalCharges` across active carriers
-- Compare total against `AOV × 0.10`
-- If exceeded → flag:
-
-> "Carrier surcharges add ${total} to shipping costs. Combined with base rates, total shipping cost may deter customers. Review each surcharge to determine if it's necessary."
-
----
-
-## Summary: Pricing sanity thresholds
-
-| Check | Threshold | Action |
-|---|---|---|
-| Excessive rate | Rate > 15% of AOV | Flag — cart abandonment risk |
-| Per-item penalty | `multiplyByQuantity: true` | Flag — discourages larger orders |
-| Free threshold too high | Threshold > 2x AOV | Flag — unreachable for most customers |
-| Free threshold too low | Threshold < 0.8x AOV | Flag — no upsell incentive, margin erosion |
-| Backup rate shock | Backup > 15% of AOV | Flag — recommend 5-10% of AOV |
-| Hidden surcharges | Total surcharges > 10% of AOV | Flag — review necessity |

package/skills/wix-manage/references/ecommerce/guardrail-shipping-health.md

@@ -1,124 +0,0 @@
----
-name: "Guardrail: Shipping Health"
-description: Shipping health score calculation (CRITICAL/POOR/FAIR/GOOD/EXCELLENT) with exact scoring criteria. Includes the mandatory business context filter for international shipping recommendations.
-layer: guardrail
-references:
-  - name: "Troubleshoot: Checkout Delivery Drop-off"
-    path: ecommerce/troubleshoot-checkout-delivery-dropoff.md
-    load: false
----
-# Guardrail: Shipping Health
-
-> **Related skills**:
-> - [Troubleshoot: Checkout Delivery Drop-off](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/troubleshoot-checkout-delivery-dropoff)
-
-## When to use
-
-Calculate the shipping health score whenever evaluating a store's shipping configuration. Use this score to prioritize recommendations and determine urgency of shipping issues.
-
----
-
-## Health score levels
-
-### CRITICAL
-
-Any of the following conditions:
-
-- `delivery_profiles` is empty AND `shipping_options` is empty
-- All regions across all profiles have `active: false`
-
-**Implication**: The store cannot ship any orders. Immediate action required.
-
-### POOR
-
-Any of the following conditions:
-
-- Only 1 delivery profile with empty regions
-- Only 1 shipping option total
-- `delivery_step_cvr` < 50% with shipping issues detected
-- All carriers have `backupRate.active: false`
-
-**Implication**: Shipping is minimally functional but has significant gaps that are likely causing lost sales.
-
-### FAIR
-
-All of the following conditions:
-
-- 1-2 delivery profiles with 1-2 active regions
-- 2-4 shipping options
-- No free shipping option available
-- OR: `delivery_step_cvr` between 50-65%
-
-**Implication**: Basic shipping is working but missing key elements that drive conversion.
-
-### GOOD
-
-All of the following conditions:
-
-- 1+ delivery profiles with both domestic and international regions
-- 3-5 shipping options including at least one free shipping option
-- 1+ active carriers
-- `delivery_step_cvr` between 65-75%
-
-**Implication**: Solid shipping setup. Optimization opportunities exist but fundamentals are covered.
-
-### EXCELLENT
-
-All of the following conditions:
-
-- Multiple active regions
-- Tiered shipping rates
-- Free shipping option available
-- Multiple carriers with backup rates enabled
-- Pickup and/or local delivery options configured
-- `delivery_step_cvr` ≥ 75%
-- No `multiplyByQuantity` pricing on any rate
-
-**Implication**: Best-in-class shipping configuration. Focus on maintaining and fine-tuning.
-
----
-
-## Business context filter (MANDATORY)
-
-**This filter MUST be applied before recommending any international shipping action.**
-
-### Check business type
-
-Inspect the store's `industry` and `businessType` fields (case-insensitive match) for any of the following keywords:
-
-- food
-- restaurant
-- grocery
-- bakery
-- catering
-- perishable
-- fresh
-- meat
-- produce
-- dairy
-- drink
-- beverage
-
-### If matched
-
-**DO NOT recommend any international shipping action.** Perishable/food businesses face regulatory, spoilage, and logistics barriers that make international shipping impractical as a default recommendation.
-
-### Identifying international regions
-
-A region is considered "international" if any of the following are true:
-
-- Region `name` contains "international" or "internacional" (case-insensitive)
-- Region `destinations[]` is empty (wildcard / all countries)
-- Region `destinations` include countries outside the store's home country
-
----
-
-## Summary: Score decision table
-
-| Score | Key indicator | Action |
-|---|---|---|
-| CRITICAL | No profiles/options or all regions inactive | Immediate setup required |
-| POOR | Minimal config, low CVR, or no backup rates | Address fundamental gaps |
-| FAIR | Basic setup, no free shipping, moderate CVR | Add free shipping, expand regions |
-| GOOD | Domestic + international, free shipping, good CVR | Optimize rates and carriers |
-| EXCELLENT | Full coverage, tiered rates, high CVR | Maintain and fine-tune |