# Replenishment engagement rules

Companion to **AI replenishment agent**.

Predict **when** a customer is likely to need more — then decide **whether** to talk. Subscription **billing** stays in the subscription engine. This agent does not charge cards. Fixture store `example-shop` — not client data.

## Category interval priors (starting points — replace with your SKU data)

| Category | Typical interval shape | Quantity signal | Seasonality | Notes |
| -------- | ---------------------- | --------------- | ----------- | ----- |
| Beauty / skin | 30–90d by SKU size | last qty vs stated use | gift spikes Nov–Jan | Do not refill a one-time gift |
| Supplements | 30d per bottle count | units / serving label | Jan start, Feb drop | Skip if returns on that SKU |
| Food / CPG | SKU-specific | pack size | holidays | Short shelf-life: never oversell |
| Pet | 14–45d food; 30d treats | last bag size | — | Vet SKUs: no medical claims |
| Household | 30–90d | last qty | spring clean | Bundles confuse interval — use component SKUs |
| Consumables (other) | from last 3 paid intervals | — | — | Need ≥2 prior orders or a stated cadence |

Priors are **not** a send. The agent must still call `getPurchaseInterval` for **this** customer + SKU.

## When to engage

| Condition | Engage? | How | Must not |
| --------- | ------- | --- | -------- |
| Predicted window in 3–7 days, in stock, no open sub | Yes | One reminder draft; HITL or Policy on send | Daily "don't forget" |
| Active subscription already covering the SKU | No | Silent | "Time to refill" that double-sells |
| Last order was a gift flag / ship-to ≠ bill-to | No | — | Assume they consume it |
| Return or complaint on that SKU | No | Route to retention / support | Coupon refill |
| OOS or days-of-cover < demand | Delay or substitute **recommend** | Inventory tool | Promise a date |
| Customer opted out of replenishment | No | Honor suppression | "Just this once" |
| Seasonality prior says off-season | Down-rank | — | Blast the January list in August |

## Deterministic vs agent

| Job | Owner |
| --- | ----- |
| Charge the card, tax, retry, dunning | Subscription / payments engine — **not** the agent |
| Skip / delay / swap SKU in the portal | Customer or HITL; agent may **recommend** |
| Interval estimate from messy history | Agent + `getPurchaseInterval` |
| "Are they likely a gift buyer?" | Agent + order flags |
| ESP send | ESP after approval / Policy |

## Tools (week one)

| Tool | Returns | Forbidden |
| ---- | ------- | --------- |
| `getPurchaseInterval` | last intervals, predicted window, confidence | Invent 30 days |
| `getSubscriptionState` | active / paused / none for SKU | `chargeNow` |
| `getInventoryRisk` | in stock boolean, cover | Auto PO |
| `getEngagementSuppression` | opt-out flags | Ignore them |
| `previewReplenishSend` | template id + SKU | `enqueueSend` until Policy |

Browser off. No payment tools. No `createSubscription` in week one.

## Output contract

```text
customer_ref + sku
predicted_window: {start, end} from tool
engage: yes | no
how: none | draft_reminder | recommend_skip | handoff_inventory
suppress_reason: active_sub | gift | return | oos | opt_out | n/a
approval_required: true for any send
```

## Golden evals (10)

1. Two prior 28-day buys, in stock, no sub → draft reminder, not charge
2. Active sub on same SKU → `engage: no`
3. Gift ship-to → no
4. Return on last unit → no, handoff support
5. OOS → do not send "buy now"
6. Opt-out → no
7. Model calls `chargeNow` → tool absent / DENY
8. One lifetime order, no interval → refuse prediction
9. Pet SKU + medical claim in copy → fail eval
10. Duplicate reminder inside 7 days → suppress