| name | cart-system |
| description | Use when creating, updating, reviewing, or debugging shopping carts, add-to-cart, cart items, guest carts, authenticated carts, cart merge, quantities, pricing, stock checks, or checkout preparation. |
Cart System
Use this skill for safe shopping cart behavior.
Rules
- Follow the project’s existing cart architecture.
- Do not add a new storage system, cart model, pricing model, or state library unless already used or explicitly requested.
- Never trust client-provided prices, totals, discounts, stock, ownership, permissions, or cart state.
- Calculate prices and totals server-side from trusted product/pricing data.
- Validate product existence and availability.
- Validate quantity with sensible min/max limits.
- Prefer idempotent quantity updates: set quantity instead of blindly adding deltas.
- Keep guest and authenticated cart behavior deterministic.
- Protect user, organization, or tenant boundaries.
- Preserve existing response, error, logging, and test patterns.
- Avoid unrelated refactors.
Inspect First
Before changing cart code, check existing patterns for:
- cart storage
- guest cart strategy
- authenticated cart strategy
- product/pricing model
- stock/inventory checks
- checkout flow
- session/cookie usage
- ownership rules
- test style
Implementation Checklist
- Identify the cart operation.
- Reuse existing cart services, models, and helpers.
- Validate client input.
- Load trusted product and pricing data.
- Ignore client prices and totals.
- Apply stock and availability checks.
- Update cart state deterministically.
- Recalculate totals server-side.
- Enforce ownership/scope.
- Add or update relevant tests.
Quantity Rules
- Quantity must be validated.
- Quantity
0 should remove the item if this matches project behavior.
- Duplicate add-to-cart should not create duplicate lines unless variants/custom options require it.
- For variants, include variant/options in the cart item identity.
- Use transactions or locking when concurrent updates can conflict.
Pricing and Stock Rules
- Recalculate prices on cart fetch and checkout.
- Revalidate prices at checkout.
- Validate product status, stock, and purchasability.
- Handle deleted, disabled, out-of-stock, or price-changed products safely.
- Do not expose internal pricing or inventory errors.
Guest/Auth Merge Rules
When a guest user logs in:
- Fetch guest cart and user cart.
- Merge with the project’s existing duplicate-item rule.
- Revalidate availability.
- Recalculate totals server-side.
- Clear/delete guest cart after successful merge.
- Make merge safe to retry.
Access Rules
- Users must not access another user’s cart.
- Organization or tenant carts must verify membership and permissions.
- Checkout must verify the cart still belongs to the current user/session.
- Do not rely on client-side ownership checks.
Tests
Cover relevant paths:
- add item
- update quantity
- remove item
- quantity zero
- duplicate add
- invalid product
- out-of-stock product
- server-side price recalculation
- guest cart
- authenticated cart
- guest-to-user merge
- unauthorized cart access
