Rules engine

Rules let you steer the AI agent without editing prompts by hand. They are the merchant-safe layer between your catalog and Zubby - boost a collection, bury a weak product, pin specific SKUs to the top of a carousel, pre-write answers to common objections, cap discounts, or nudge the AI's tone. Everything here lives under Growth → Rules & Voice in the sidebar and is scoped to a single store.

The Rules area is four pages. The main Rules & Voice page handles broad merchandising and voice controls; the Merchandising (/app/<storeId>/rules/merchandising) and Objections (/app/<storeId>/rules/objections) pages are focused authoring surfaces for two high-value rule kinds; and Effectiveness (/app/<storeId>/rules/effectiveness) reports how each rule is actually performing and links to both authoring pages.

Rules are not the knowledge base

Rules shape what to push and how to speak. They are the wrong place for store facts - shipping windows, return policy, FAQ answers. Put those in Knowledge so the AI can cite them. A good split: facts in Knowledge, behavior in Rules.

Rules & Voice (the main page)

This is the general-purpose rule list. Each rule has a type, a target scope, an optional target value, a description, and a weight modifier. Click Add Rule to open the editor; first-time authors can start from a preset (push a collection, never recommend a product, favor a category, approved offer) which pre-fills sensible defaults.

Rule types

Type	What it does
Boost	Promotes the target earlier in search and recommendation results. Weight above 1 lifts it (a preset uses 1.5–1.8x).
Exclude	Hides the target from search and recommendations entirely. Use for discontinued or out-of-strategy items. Weight 0.
Block Claim	A phrase the AI must never say. Blocked phrases are enforced two ways: they are banned from every AI reply (the guardrail aborts a response that would contain one), and products whose title or description contains the phrase are filtered out of retrieval.
Tone	Applies a voice override the AI follows on every message - for example “always warm and concise, never pushy.” Tone rules layer after the brand voice you set in the Widget Designer or `Settings → AI Setup`, so on any conflict the Rules-page tone wins.
Discount Limit	Controls what the AI may offer when a shopper asks for a deal. You attach an approved offer (type, label, code, minimum subtotal, notes); the weight becomes the maximum percent-off allowed. Without an approved offer, the AI refuses ad-hoc discounts.

Target scope and value

Scope decides what the rule applies to: Global (all products, no target value needed), Collection, Product, or Category. For non-global scopes the editor suggests real entities from your synced catalog - click a suggestion chip so the target matches an actual product, collection, or category rather than a guessed ID. Product targets use the platform product ID; collections use the internal collection ID.

Weight modifier

For boost and exclude rules the weight is a multiplier: 1.0 is normal, above 1 promotes, below 1 de-prioritizes, and 0 excludes. For a discount-limit rule the same field means something different - it is the maximum percent-off the AI may ever quote for that offer.

Managing rules

Each rule card shows an inline IF/AI preview - what the shopper does and what the AI does in response - so you can sanity-check behavior before saving. You can toggle a rule on or off without deleting it (disabled rules dim and stop firing), edit it, or delete it. Select multiple rules with the checkboxes to enable, disable, or delete in bulk.

Merchandising - pre-merchandised carousels

The /app/<storeId>/rules/merchandising page pins specific SKUs that should lead the AI's product carousel whenever a shopper's message contains your trigger phrase. Think “wedding gift” → your three hero registry products always show first. Fields:

Trigger phrase - matched as a case-insensitive substring against the shopper's message (e.g. wedding gift).
Internal label - a name for your own reference (optional).
Pinned internal product IDs - the internal product UUIDs from the catalog page, comma- or whitespace-separated. Up to 6 pinned products show per turn.
Priority - 0–100; when several rules match, pins fill from the highest-priority rule down until the 6-pin cap is hit.
Active and Notes - toggle off to disable without deleting; notes are internal only.

Pinned items still respect filters

Pinned SKUs are not forced past reality. They still obey in-stock and price-band filters - a pinned product that is out of stock or outside the shopper's budget will not appear. Pin generously, but expect the agent to skip anything that would be a bad recommendation.

Objections - pre-authored answers

The /app/<storeId>/rules/objections page lets you write response guidance the AI should reach for when a shopper raises a known objection like “too expensive” or “what if it doesn't fit?” Each objection response has:

Category - one of price, fit, shipping, returns, quality, stock, comparison, trust, or general.
Trigger phrase - case-insensitive substring match against the shopper's message (e.g. too expensive).
Response template - the guidance the AI follows when it fires (e.g. lead with the value prop, mention the 30-day return policy, offer free shipping over $75).
Priority - 0–100; higher wins. Up to 2 objection rules can fire per turn.
Active and Notes - same toggle and internal-note behavior as merchandising rules.

Write templates as guidance, not a rigid script. The AI weaves the template into a natural reply for that specific shopper rather than pasting it verbatim, so it still reads as a conversation.

Effectiveness - is it working?

The /app/<storeId>/rules/effectiveness page estimates how each trigger-phrase rule performed over the last 30 days. For every objection and merchandising rule it measures two things:

Hits - conversations in the window whose shopper messages contained the rule's trigger phrase.
Carts - how many of those conversations went on to produce an add-to-cart event, shown as a conversion rate.

Three summary cards at the top show active triggers, trigger hits over 30 days, and the portfolio cart rate. Rows are sorted by hits, then by conversion rate, so the rules pulling the most weight surface first. Rates above 5% are highlighted; a rule with 10+ hits and a 0% rate is greyed out. These are interface heuristics, not validated performance benchmarks or instructions to retire a rule automatically.

Effectiveness is a heuristic

Zubby does not stamp a rule ID on every recommendation, so hits and conversion are estimated by matching trigger phrases in shopper messages - not exact attribution or causal lift. Comparisons are directional: rules may overlap, reach different audiences, and have incomplete event coverage. Review examples and controlled tests before changing policy or declaring a winner. Triggers shorter than three characters are skipped.

How rules reach the agent

Matching rules are resolved per turn and injected into the conversation as constraints the agent must respect - boosts and excludes reweight retrieval (excludes are absolute and cannot be overridden by a boost), block-claim rules ban phrases from replies and filter matching products, tone rules shape wording, and discount limits cap what the AI may offer. This is the same mechanism the AI agent uses for knowledge and playbooks: merchant intent in, grounded behavior out.

For voice specifically, the prompt is layered: your brand voice (Widget Designer → Behavior, or Settings → AI Setup → Brand voice) renders first, then any Rules-page tone rules. Because tone rules come last, they win whenever the two disagree - use brand voice for the default personality and tone rules for hard overrides.

How to author your first rule

Open Growth → Rules & Voice and click Add Rule.
Start from a preset - Push a collection harder, Never recommend a product, Favor a category, or Approved offer - so the type, scope, and weight are pre-filled with sensible values.
Pick the target from the suggestion chips rather than typing an ID by hand; the chips come from your synced catalog, so the rule is guaranteed to match a real product, collection, or category.
Check the inline IF/AI preview on the saved rule card - it shows what the shopper does and how the AI responds - then watch the Recommendations page after a week of traffic to see whether the rule is moving what the AI actually surfaces. (Trigger-phrase rules - objections and merchandising - report in /app/<storeId>/rules/effectiveness instead.)

Example: test a trigger and a conflict

This synthetic example uses two merchandising rules for “wedding gift”. Give the first priority 80 and the second priority 20, with different known in-stock products. Ask “I need a wedding gift” and check the returned cards against the priority order and six-pin limit. Ask “I need a birthday gift” to test the nonmatch. Then exclude one pinned product and rerun the first question: exclusion and stock/price filters must still apply. Check the transcript and product cards rather than relying only on the preview. Disable the test rules afterward.

Keep exact policy facts in Knowledge or Locked Facts. An objection template can be paraphrased and should not be treated as guaranteed verbatim wording. Use controlled experimentswhen the decision needs evidence beyond a phrase-match report.

Gotchas

Trigger matching is plain case-insensitive substring matching, not fuzzy or semantic. too expensive will not catch “pricey” - add multiple rules or phrasings for full coverage.
Priority breaks ties; among rules that match, the highest priority wins (and a fixed number fire per turn - 6 pinned products, 2 objection responses).
Disabling beats deleting when you are experimenting - a toggled-off rule keeps its history and shows up in Effectiveness so you can compare before/after.
Discount rules are the only safe way to let the AI mention a code. Without an approved offer the agent refuses discounts, which is the intended default.

How the AI agent works
Playbooks & agent-assist - for step-by-step in-chat procedures
Knowledge base - for store facts and policies
Conversations - where rule effects show up in real transcripts