| name | vertical-retail |
| description | Retail & e-commerce domain knowledge for SMB storefront products (storefront, inventory, pricing, cart-recovery). Codifies the vocabulary (SKU vs variant, reorder point, COGS/margin, ATS, AOV), the non-obvious rules (Shopify owns the storefront — don't fight it head-on; the wedge is multichannel inventory + reorder and cart recovery), the must-model entities (Product→Variants matrix, channel-aware InventoryLevel, ReorderRule, PricingRule, AbandonedCart), and what a naive build gets wrong (no variant model, single-channel inventory, reorder without lead-time/safety-stock). Applied by architect/pm during spec authoring so they aren't naive about retail; checked implicitly by pci-reviewer + cms-reviewer. |
| when_to_use | Apply when architect or pm is speccing a retail / e-commerce product:
- storefront / inventory / pricing / cart-recovery for an SMB seller
- any catalog, checkout, stock-tracking, promotion, or abandoned-cart feature
Do NOT apply to non-commerce verticals, or to heavy payments/tax work (defer those to pci-reviewer / billing).
|
| effort | low |
| allowed-tools | Read, Write, Grep, Glob |
| paths | ["docs/architecture/**","docs/plans/**","docs/design/**"] |
Retail & e-commerce — spec it like someone who's run a store
The SMB retail buyer already pays Shopify ($39–399/mo + 2.9%), BigCommerce, Wix, Ecwid, or
WooCommerce. They are not naive — so the spec can't be either. A storefront that "has products
and a cart" is table stakes; the value is in the parts those platforms do badly. Read this
before writing the catalog/inventory/pricing/cart sections of any retail ARCH or PLAN doc.
1. Domain vocabulary (use these exact words)
- SKU vs variant — a variant is one buyable configuration (Red / Large); its SKU is
the unique code that variant ships and is counted under. A "product" is the parent; you stock,
price, and sell variants, not products.
- Multichannel / omnichannel — selling across several channels (own storefront, Amazon,
eBay, in-store POS, Instagram). Omnichannel additionally means one inventory pool behind all
of them. Channel-awareness is the whole game for SMB inventory.
- Reorder point — stock level that triggers a purchase order = (avg daily demand × lead
time in days) + safety stock. Lead time = supplier days from order to receipt.
Safety stock = buffer for demand/lead-time variance. Reordering without all three is wrong.
- COGS (cost of goods sold) and margin = (price − COGS) / price. Landed cost = unit
cost + freight + duties + handling; margin must use landed cost, not invoice cost.
- ATS / available to sell = on-hand − allocated (reserved by open orders) − safety stock.
Customers buy against ATS, never raw on-hand.
- Backorder vs preorder — backorder = out of stock now, will refill (sell against incoming
PO). Preorder = not released yet, future availability date. Different fulfillment promises.
- Cart abandonment rate = 1 − (completed checkouts / carts created); industry ~70%.
- AOV (average order value) and conversion rate = orders / sessions. The two levers
pricing/promotions move.
- Fulfillment — pick/pack/ship. Dropship = supplier ships direct, seller never holds
stock (so "stock" is the supplier's ATS feed, not yours).
- MAP (minimum advertised price) — supplier-imposed price floor; a pricing rule must respect
it or the seller loses the brand.
2. Non-obvious domain rules
- Shopify owns the storefront — don't fight it head-on. A me-too checkout loses. The wedge is
the platforms' : , and .
Spec the storefront as competent-and-owned, and put the differentiation in the other three.
