Example: Catalog & Sync
A playbook for integration and data-sync tickets — the category where the root cause is usually an expired credential.
Products, inventory or orders that are not flowing between your platform and something external. Almost always a credential, a rate limit, or a worker that died — which makes it a good example of a playbook whose value is mostly in the ordered checklist.
Fields
Name
Catalog & SyncDescription
Tickets about data not syncing between the platform and an external system: product
catalog imports, inventory counts, order exports, and connected-store integrations
that have stopped updating.Routing hints
sync, "not syncing", "products missing", "0 items", catalog, import, export,
inventory, "stock not updating", "connection lost", reconnect, "stuck at", OAuth,
"reauthorize", integration disconnectedTriage instructions
A sync that reports zero items is almost never an empty catalog. It is a broken
connection reporting success. Start from that assumption.
Check in this order:
1. MongoDB: the merchant's integration/connection document. Look at the token expiry
and the last successful sync timestamp. An expired OAuth token is the single most
common cause in this category by a wide margin.
2. The sync run records for this merchant: did runs happen, and what did they report?
A run that completed with 0 items is different from no run at all, and points at a
different cause.
3. app-sync-* OpenSearch logs for this merchant_id around the last attempted run.
Look for 401/403 from the external provider and for rate-limit responses.
4. Sentry for exceptions from the sync worker in the same window.
5. Kubernetes: the state of the sync-service deployment. CrashLoopBackOff explains
every merchant's sync stopping at once and should be checked before concluding
anything merchant-specific if the failure is broad.
Known causes, most to least common:
- expired or revoked OAuth token — merchant must reconnect the integration
- external provider rate limiting, visible as 429s in the sync logs
- sync worker crashed or is in CrashLoopBackOff, affecting everyone
- a schema change on the external side breaking the mapping for a specific field
- the merchant genuinely has no products in the source
Conclusions:
- Establish scope before cause: check whether other merchants synced successfully in
the same window. A token problem is one merchant; a worker problem is all of them.
- If the token expired, say so and state that the merchant must reconnect. Do not
describe it as a platform outage.
- If the sync worker is unhealthy, this stops being a support ticket — say so
explicitly and name the deployment.Data sources
org-mongodb, org-opensearch, org-sentry, org-kubernetesVisibility
Everyone in the organization.
Why it is scoped this way
Connection state lives in MongoDB, sync attempts in OpenSearch, worker exceptions in
Sentry. Kubernetes is included for one specific reason: sync failures are the category
most likely to be caused by a dead worker, and being able to see
CrashLoopBackOff turns a long merchant-by-merchant investigation into a
one-tool-call answer.
Payments systems are excluded. A catalog sync problem is never in the payments database, and letting the agent look there is pure cost.
Tuning it
If your integrations are with a small number of named external platforms, add their names to the routing hints — customers name the platform, not the word "sync", and that is what makes classification land.
Example: Checkout & Orders
A playbook for the buyer-facing half of payments — declines, failed checkouts, and orders that did not appear.
Example: Platform Reliability
A playbook for "everything is slow" and "the site is down" — scoped to infrastructure, and the one worth pairing with a scheduled report.