JUNOHUB-test/docs/vendor_use-case_implemenation.md
Saad Mohsin 80b53535c1 yes
2026-04-12 04:15:11 +05:00

47 KiB
Raw Blame History

Vendor use-case knowledge modules & L1 agentic implementation plan

Read this first (integration). This file is an implementation-oriented plan meant to be merged into an existing codebase (Shopify sync, dashboard, DB already in place). You are not required to follow the module codes, shared_field_id strings, table/column names, tool names, flags, slot keys, or any other rigid-looking labels in this document when they would create conflict with your current schema, migrations, types, or APIs. Those conventions exist only to keep the spec internally consistent and to explain how the system should behave. Map concepts, not strings: keep the ideas (which flows are L1 vs ticket vs KB, verification rules, prerequisites, tool-call shape); rename and wire to whatever your project already uses. If spec and repo disagree on names, default to the repo unless you explicitly refactor.

Same caution, shorter: Identifiers in this doc are illustrative, not a mandate. Codebase wins over literal tags here. Preserve behavior and structure, not every ID.

Purpose. This document defines shortlisted customer-support use-cases as optional sub-modules: vendor knowledge (FAQ-style), L1 transactional automation (read/act on data you already sync from Shopify into your database), and ticketing (human resolution). It also specifies two customer interfaces (email + storefront widget), verification (email + OTP only), and constraints so implementations stay consistent.

Scope (agentic layer only). Shopify store, vendor dashboard, and database hydration from Shopify are assumed to exist. This plan covers the L1 automation layer (intent handling, retrieval, slot filling, verification, safe responses, ticket creation). It does not describe full end-to-end replacement of human support.

Data access (tool calls). The agent does not “know” order lines, inventory, tracking, or category metadetails by default. Implementation must expose tool calls (or equivalent server-side functions) that query your database using your actual schema and field names for each store. Answers for transactional flows and for catalog metadata flows are only as good as (a) what is synced into the DB and (b) which tools the orchestrator is allowed to invoke for that module. Document concrete tool names, parameters, and return shapes in engineering specs for your real schema — those names need not match any examples elsewhere in this document (see Read this first above).

Excluded use-cases (out of scope for this framework):

  • Subscription / repeat orders
  • Wholesale / B2B / large orders
  • Account & security (e.g. Shopify permission / identity beyond email+OTP)
  • VIP / loyalty context
  • Shopify customer login and magic-link verification (explicitly not used)

0. What we automate vs what humans do

0.1 L1 only — not the whole pipeline

  • L1 = deflection and safe, bounded automation: answer from knowledge, read order/product state from your DB, perform allowed actions (e.g. cancel when rules say yes), and hand off when the job requires judgment, negotiation, or operational access beyond the playbook.
  • Tickets = default path when the use-case is human work (order change, warranty processing, payment disputes, complaint resolution, return/exchange handling, etc.). There is no generic end-to-end workflow for tickets in the agentic sense: a real human owns the ticket. The agent may draft context for the human (summary, slots filled, policy snippets), but resolution is human.

0.2 Three pillars (every module maps to one primary pillar)

Pillar Meaning Typical outputs
Knowledge (FAQ) Answers from vendor-configured text + embeddings / RAG; no order mutation; may not need identity. Policy explanations, links, “how we work.”
Transactional L1 Uses verified identity + prerequisites (e.g. order id); reads DB (and optionally acts where allowed). Order status, tracking snapshot, cancel eligibility + cancel, refund status lookup, inventory lookup.
Ticket-led After verification (when needed), create or continue a ticket; customer-facing reply is acknowledgement + expectations; human executes. Order change, warranty, payment disputes, wrong-item resolution, return/exchange initiation, complaints, many shipment exceptions.
Catalog metadata (DB-backed) Answers grounded in structured fields synced from the storefront (e.g. category metadetails), retrieved via tool calls — not free-form vendor FAQ text for those facts. Category-wide sizing notes, materials, care, compatibility text the merchant attached at category level; applies to all products in that category.

Note: “Refund policy” (e.g. “how long do refunds take?”) is Knowledge. “Refund status for my order” is Transactional (needs identification + order/return context in DB).

Category metadetails module (vendor toggle). Merchants can maintain details at the category level in Shopify (and equivalents); once synced to your DB, that data can power answers (e.g. fit, fabric, voltage) across every product in those categories. In the product, the vendor has a single switch: enable or disable use of category metadetails for automation — no per-category granularity in v1. When disabled, the agent must not use tool calls that return category metadetails (fall back to KB, PDP links, or ticket). When enabled, the agent may answer from metadetails of all categories/products the store has synced, subject to intent and tool-call availability.

0.3 Tickets and email

  • Tickets are internal objects; conversation with the customer for ticket-heavy flows is still primarily email (and mirrored logic on the widget where applicable).
  • If the customer is already on email, opening a ticket (e.g. return initiation, complaint) can be initiated automatically from that thread once rules are satisfied.
  • If the customer is on the widget, they complete email + OTP + session first; then “open a ticket” creates the ticket and subsequent human↔customer dialogue happens over email (or the same channels you define in sf_support_channels).

1. Customer interfaces

1.1 Email

  • Identity signal: the sender address (From:) is the customer email for that thread.
  • Strict rule (transactional): for any fiber / sensitive action (order status, cancel, refund status, shipping details tied to an order, etc.), the only email identity you trust for lookup is From matches the email on the order / customer record in your database. The customer cannot ask for someone else’s order from their own inbox; they must send from the email that placed the order (e.g. they cannot use their personal Gmail to query a friend’s order placed under the friend’s email).
  • Verification path on email: no OTP in v1 of this plan for email (optional future); trust is email alignment with DB. If From is not associated with any customer/order, respond with a generic safe message (do not confirm whether an order exists for another email) and instruct them to contact support from the email used at checkout.
  • Multi-order disambiguation: if From matches a customer with multiple open or recent orders, L1 lists candidate orders (e.g. id, date, short descriptor) and asks which order they mean before fetching full details or acting.

1.2 Storefront widget (chat)

  • Unauthenticated path: if the user only needs Knowledge (FAQ) and the vendor has enabled that module, answer using RAG/KB without collecting email (no session required for pure FAQ).
  • Transactional path: to run any Transactional L1 or Ticket-led flow that depends on who the customer is:
    1. Collect email address (the one they assert is their order email).
    2. Start a server-side session bound to that email attempt; show the user that the session is valid for a fixed TTL (e.g. 1 hour) and that further questions in that window use this context.
    3. Send OTP to that email; user enters OTP in the widget.
    4. On success, mark session verified for that email; proceed with slot filling (order id, product name, etc.) and L1 or ticket creation.
  • No Shopify login, no magic links — only email + OTP for widget verification.

1.3 OTP (widget) — behavioral requirements

  • Rate-limit sends and attempts; invalidate OTP after use or expiry.
  • Session store: session_id → asserted_email, verified_at, expires_at, store_id, optional bound_order_id after disambiguation.
  • After TTL expiry, re-OTP required for any new transactional request.

2. Verification, confidentiality, and prerequisites (cross-cutting)

2.1 Constraint: no cross-email order access

  • You must not disclose order data unless the verified channel identity matches the customer/order email in the database (email channel: From; widget: OTP-proved email).
  • Friend’s order: impossible to service from the wrong inbox; customer must use the purchaser’s email (and that person must be the one in the thread or OTP flow).

2.2 Prerequisites pattern

For each Transactional or Ticket-led module, define:

  • Required slots (e.g. order_id, product_query, issue_subtype).
  • Verification gate: email_aligned (email) or otp_verified_session (widget).
  • L1 action: read-only, read+act (limited), or create ticket only.

2.3 Slot filling and back-and-forth

  • Orchestrator state: collect_slots → verify (widget OTP) → execute_l1 or open_ticket → respond.
  • Ask only for the next missing prerequisite.
  • Reuse one verified session on the widget for multiple questions within TTL (e.g. status then tracking for same order).

2.4 Module anatomy: three types of configuration / questions

Every use-case module is implemented as a bundle of three layers. The vendor dashboard and engineering manifests should reflect these explicitly (tabs, accordions, or sections).

Type Name Who fills it What it controls
Type 1 Policy & messaging Vendor (questionnaire) Text the agent may cite or blend into replies: tone-adjacent facts, “what we tell customers,” links, windows, exclusions — stored as shared_field_id (or your equivalent). Does not replace DB facts for transactional answers.
Type 2 Verification & prerequisites Platform rules (+ minimal vendor toggles if you add them later) Who is allowed to run this flow and which slots must be collected first: From email vs order email, widget email + OTP + session TTL, order_id, product_name, disambiguation when multiple orders match, etc.
Type 3 L1 automation & ticketing Engineering (manifest) + vendor enable After Type 2 passes: tool calls / DB reads, optional writes (e.g. cancel), composition of the reply; and when to open a ticket, what to attach, and that humans own ticket resolution.

How they work together (example: ORDER_STATUS):

  • Type 1: Vendor answers how long processing usually takes, what you say if pre-ship delay, shipping regions, how customers find order # — so the reply can wrap factual status with on-brand messaging.
  • Type 2: Customer must be verified (email on channel = email on order, or widget OTP); order_id required or disambiguated from a short list.
  • Type 3: L1 reads order + fulfillment from DB via tools, replies with status + tracking snippets + Type 1 copy; if the case is outside playbook (data missing, anomaly), open ticket for a human.

Modules that are “mostly FAQ” still have all three types logically: Type 1 = full questionnaire; Type 2 = often none (no identity); Type 3 = RAG/KB retrieval only, plus optional “suggest human / ticket” if out of scope.

Modules that are “mostly ticket” have heavy Type 3 ticket path: L1 may only intake + acknowledge + create ticket; Type 1 still supplies policy snippets in the auto-reply.


3. Use-case catalog — categorization (vetted)

Legend

  • K = Knowledge (FAQ / KB; module enabled gates automation).
  • T = Transactional L1 (DB read / limited write after verification + slots).
  • X = Ticket-led (human resolves; L1 may intake + acknowledge + ticket).
  • Catalog metadata (DB-backed) = see §0.2; answers use tool calls against synced category metadetails when CATEGORY_METADETAILS is enabled (no per-category toggle in v1).
Module code Customer-facing use-case Primary pillar Prerequisites (typical) L1 automation (agentic) Human / ticket
ALL Global store context — — Informs all replies —
FAQ General policies & “how we work” K None for pure policy RAG / structured FAQ; refund policy lives here, not “status” If out of scope → suggest email or ticket
CATEGORY_METADETAILS Category-level product details from storefront sync Catalog metadata (DB-backed) Product or category resolution (name/SKU → category); module must be enabled by vendor Tool calls to DB: read category metadetails fields for the resolved category(ies); use for factual answers store-wide If disabled, off, or no row → KB / PDP link / ticket
PRODUCT_FIT Product fit, sizing, compatibility K (optional light T: product resolve) Product name/SKU for specificity Answer from KB + category metadetails (if CATEGORY_METADETAILS enabled) via tools + product metafields/chunks; link to PDP chart Edge cases → ticket
STORE_LOCAL Store hours, pickup, local K None KB only —
FEEDBACK After-resolution feedback K Optional ticket id Link to survey / ask once Negative follow-up → human
HUMAN_ESCALATION “I want a person” K / routing None or context Ack + routing copy + create ticket if policy says so Human handles queue
ORDER_STATUS Where is my order T Verified identity + order_id (or disambiguation) Read order state from DB; reply with status summary If anomaly outside playbook → ticket
ORDER_SUMMARY Order summary / receipt recap T Same Read line items / totals from DB Tax invoice edge cases → ticket if vendor policy says
SHIPPING_TRACKING Carrier, tracking, ETA T Same Read tracking fields from DB for that order Carrier claim / dispute → X
ORDER_CANCEL Cancel order T Same + business rules in DB Eligibility check + cancel if allowed; else explain from KB If ambiguous or edge case → X
REFUND_STATUS Status of my refund / return payout T Verified identity + order (or return) reference Read refund/return state from DB if modeled; else templated “we’ll update you” + X Human if data missing
INVENTORY_STOCK Is this in stock T product_name / SKU (widget may need session only if tied to customer cart—optional) Read inventory from DB Disambiguation across many SKUs
NOT_RECEIVED_MARKED_DELIVERED Tracking says delivered, I don’t have the parcel X Verified identity + order_id L1: confirm tracking snapshot + vendor policy snippet + open ticket Human investigates carrier / claim
SHIPMENT_STUCK_OR_DELAYED Shipment not moving / very late vs expectation X Verified identity + order_id L1: last known scan + policy snippet + open ticket Human chases carrier / ops
PAYMENT_PROBLEM Double charge, wrong amount, promo failed, etc. X Verified identity + order reference when payment is order-scoped; some sub-intents need last4 / date as slots L1: structured intake + ticket; no automated money movement Human + finance tools
ORDER_CHANGE Change address / items / qty X Verified identity + order_id + requested change L1: open ticket + acknowledgement (human decides feasibility) Human confirms “possible / not possible”
RETURN_EXCHANGE Start return or exchange X Verified identity + order_id (+ reason) L1: policy from KB + open ticket (or portal link if you add later) Human / ops fulfills RMA
WARRANTY Warranty claim (post–return window) X Verified identity + proof-of-purchase / order L1: intake + ticket Human adjudicates
WRONG_ITEM Wrong / damaged / missing item X Verified identity + order_id + issue type (+ photos on email) L1: acknowledge + policy + ticket with structured fields Human resolves (reship/refund)
COMPLAINT Strong dissatisfaction X Strict verification same as other fiber flows L1: empathetic ack + ticket + severity Human owns resolution

3.1 Per module: Type 1 (policy) · Type 2 (verification) · Type 3 (L1 / ticket)

Use this matrix with §2.4 and §7. Type 1 detail lives in the §7 tables (shared_field_id). Type 2 and Type 3 are the minimum spec for manifests and runtime.

Module Type 1 — Policy & messaging (vendor Qs) Type 2 — Verification & prerequisites Type 3 — L1 automation & ticketing
ALL Global G1–G12 (applies across modules) N/A at module level Wires into prompts for every reply
FAQ FQ1–FQ8 None for anonymous FAQ RAG / structured FAQ; OOD → suggest email or ticket
CATEGORY_METADETAILS None (store toggle only) Vendor enables feature; product/category resolution (name/SKU → category) Tool calls read category metadetails from DB; if off/empty → fallback KB or ticket
PRODUCT_FIT PF1–PF4 Optional product/slot for specificity KB + optional metadetails tools; edge → ticket
STORE_LOCAL SL1–SL4 None KB-only replies
FEEDBACK FB1–FB3 Optional link to prior ticket/context Send CSAT / link; negative path → human
HUMAN_ESCALATION HE1–HE4 None or minimal context Ack + routing; create ticket if policy requires
ORDER_STATUS OS1–OS5 (+ ALL for order# help) Email = order email OR widget OTP session; order_id or multi-order pick L1: tool read order/fulfillment → reply; Ticket: anomaly / missing data / out-of-playbook
ORDER_SUMMARY SM1–SM4 (+ ALL) Same as order-scoped flows L1: read line items/totals → reply; Ticket: tax/invoice edge cases per vendor policy
SHIPPING_TRACKING ST1–ST6 (+ ALL) Same as ORDER_STATUS L1: read tracking fields → reply; Ticket: carrier dispute / claim handoff
ORDER_CANCEL CX1–CX5 (+ ALL) Same as ORDER_STATUS L1: eligibility + cancel if allowed; else KB + Ticket if ambiguous
REFUND_STATUS RF1–RF6 (+ ALL) Verified identity + order/return reference L1: read refund state if in DB; else ack + Ticket
INVENTORY_STOCK IV1–IV5 product_name/SKU; widget OTP optional per product policy L1: inventory tool read; heavy disambiguation → clarify or ticket
NOT_RECEIVED_MARKED_DELIVERED NR1–NR2 (+ ALL) Same as order-scoped L1: tracking snapshot + policy text + always open ticket for human
SHIPMENT_STUCK_OR_DELAYED SD1–SD3 (+ ALL) Same as order-scoped L1: last scan + policy + open ticket
PAYMENT_PROBLEM PP1–PP6 (+ ALL) Verified identity; order id when payment is order-scoped; else intake fields L1: structured intake + ticket; no automated money movement
ORDER_CHANGE OC1–OC4 (+ ALL) Same as order-scoped + requested change captured L1: open ticket + ack only; human decides feasibility
RETURN_EXCHANGE RE1–RE6 (+ ALL) Same as order-scoped + reason optional L1: policy in reply + open ticket (or portal later)
WARRANTY WA1–WA5 (+ ALL) Verified identity + proof-of-purchase / order L1: intake + ticket; human adjudicates
WRONG_ITEM WI1–WI6 (+ ALL) Same as order-scoped + issue type; email may attach photos L1: ack + policy + ticket with structured fields
COMPLAINT CP1–CP6 (+ ALL) Strict same as other “fiber” flows L1: empathetic ack + ticket + severity; human owns

Removed vague module: DELIVERY_PROBLEM is removed as a single umbrella. Use NOT_RECEIVED_MARKED_DELIVERED and SHIPMENT_STUCK_OR_DELAYED so intents and playbooks stay specific.


4. Design principles (knowledge modules)

4.1 Modular enablement

  • Each use-case = one sub-module. Vendor enables modules they want.
  • In the product UI, each enabled module should expose three areas aligned with §2.4: (1) Policy & messaging (vendor questionnaire), (2) Verification & prerequisites (read-only copy of platform rules + any future vendor toggles), (3) L1 & ticketing (read-only summary or advanced: what automation does vs when tickets open) — exact layout is product design.
  • Type 1 complete: enabled when required vendor questions (shared_field_id) for that module are filled (where the module has a questionnaire).
  • Transactional / ticket modules: additionally require technical readiness (e.g. order data in DB, ticket pipeline) — product-defined.
  • CATEGORY_METADETAILS: no vendor questionnaire — only a single store-level toggle (on / off). On = agent may use tool calls to read category metadetails for all synced categories/products; off = those tools are not invoked for customer answers. No per-category enable/disable in v1.

4.2 Single source of truth (shared answers)

  • Vendor questions map to shared_field_id. Same id = one value; edit propagates everywhere to avoid contradictions.

4.3 Duplication in the UI

  • Same question may appear in multiple modules for context; storage is still keyed by shared_field_id.

4.4 ALL (global)

  • Baseline questions apply to every store regardless of modules.

4.5 Document boundaries

  • This doc specifies business rules and conceptual field identity for alignment across modules. Schema, UI copy, exact OTP TTL, and chunking strategy are implementation details elsewhere — and physical schema / API names need not match the shared_field_id or module codes in this file (see Read this first (integration) at the top).

5. Shared field ID reference (cross-module truth)

The keys in the first column are spec labels for “one conceptual answer, many modules.” In your app they might be DB columns, JSON keys, or CMS field handles with different names — that is expected when integrating (see Read this first).

shared_field_id Typical use
sf_brand_display_name Brand as customers know it
sf_store_one_liner What you sell / for whom
sf_official_languages Languages you support in writing
sf_support_channels Email, phone, chat, hours
sf_support_first_response_sla Expected time to first human/bot reply
sf_tone_and_words_to_avoid Voice + banned terms
sf_order_id_help How customers find order # / confirmation
sf_first_message_checklist What to include when contacting support
sf_policy_link_terms Terms of sale URL
sf_policy_link_privacy Privacy policy URL
sf_policy_link_returns Return policy URL (if separate)
sf_privacy_support_paragraph Short: how data is used in support
sf_shipping_regions_served Where you ship
sf_shipping_regions_excluded Where you do not ship
sf_processing_time_before_ship Dispatch / handling time
sf_carriers_and_tracking_policy Carriers + when tracking is provided
sf_shipping_methods_and_transit Methods + realistic transit ranges
sf_shipping_cost_model Free/paid/flat/dynamic
sf_dispatch_cutoff Same-day rules if any
sf_address_correction_policy Wrong address, failed delivery fees
sf_customs_duties_policy International duties disclaimer
sf_delivered_not_received_policy “Delivered but I don’t have it”
sf_major_delay_communication Strikes, weather, backlog messaging
sf_stuck_shipment_customer_steps What customer should do while shipment appears stalled
sf_cancellation_window When cancel is allowed
sf_cancellation_how_to_request How customer asks to cancel
sf_cancellation_preorder_digital Special rules if applicable
sf_order_change_allowed_until Until when edits are possible (for KB / human context)
sf_order_change_how_to_request How to request change (human path)
sf_order_change_not_possible_next_step After cutoff / shipped
sf_return_window Days / trigger event
sf_return_condition_requirements Tags, unworn, packaging
sf_return_shipping_payer Who pays return shipping
sf_exchange_policy Swap vs credit vs refund
sf_how_to_start_return Portal/email/steps
sf_non_returnable_categories Final sale, hygiene, etc.
sf_refund_methods Original payment vs store credit
sf_refund_timeline_after_approval Time to money back
sf_partial_refund_rules Open box, missing parts
sf_store_credit_rules Expiry, combinable
sf_payment_methods_accepted Cards, wallets, regional limits
sf_promo_discount_rules Stacking, exclusions
sf_tax_display_policy What’s included at checkout
sf_price_adjustment_policy Post-purchase price match if any
sf_failed_payment_guidance What customer should retry
sf_wrong_item_report_deadline Time limit to report
sf_wrong_item_evidence Photos, packing slip, etc.
sf_wrong_item_remedies Reship, refund, return-first (human executes)
sf_damage_carrier_vs_warehouse How you explain difference
sf_warranty_duration_scope Length + what’s covered
sf_warranty_voiders Misuse, unauthorized repair
sf_warranty_claim_process Proof, repair, replace
sf_sizing_fit_guidance Fit notes + size chart link
sf_compatibility_notes Devices, voltage, region
sf_materials_care_limitations Care, allergens, limitations
sf_back_in_stock_policy Waitlist / notify / none
sf_preorder_policy Charge timing, ship-by, cancel
sf_discontinued_product_policy Alternatives / final sale
sf_physical_locations_hours Addresses + hours + holidays
sf_pickup_rules Hold time, ID, process
sf_instore_vs_online_inventory Same stock or not
sf_human_escalation_when Clear “ask a human” path
sf_complaint_acknowledgement_sla How fast you acknowledge
sf_complaint_supervisor_escalation When a lead reviews
sf_abusive_contact_policy Neutral boundary statement
sf_feedback_csat_process Survey link / when sent
sf_order_summary_tax_invoice_note Invoices, VAT, limitations
sf_double_charge_intake What customer should send for duplicate charge claims

6. ALL — Global / store-wide questions

# Question (vendor-facing) Why it matters shared_field_id
G1 What is your brand or store name as customers should see it? Consistent identity. sf_brand_display_name
G2 In one or two sentences, what do you sell and who is it for? Grounds answers. sf_store_one_liner
G3 Which languages do you officially support in email/support? Sets expectations. sf_official_languages
G4 What are your official support channels (email, phone, chat) and hours? Human + ticket paths. sf_support_channels
G5 Typical first response time for human support? Trust / SLA. sf_support_first_response_sla
G6 Tone and words or promises to avoid. Brand-safe automation. sf_tone_and_words_to_avoid
G7 How customers find order number / confirmation. All order-related flows. sf_order_id_help
G8 What customers should always include when contacting support. Faster resolution. sf_first_message_checklist
G9 Link to terms of sale. Legal grounding. sf_policy_link_terms
G10 Link to privacy policy. Trust. sf_policy_link_privacy
G11 Link to return / refund policy if separate. Canonical policy URL. sf_policy_link_returns
G12 Short paragraph: how data is used in support. Privacy framing. sf_privacy_support_paragraph

7. Per-module vendor question sets

Each subsection follows §2.4 (three types):

Type Role in this section
Type 1 Policy & messaging — vendor questionnaire rows in the table (shared_field_id). Completing required Type 1 fields gates Knowledge for that module.
Type 2 Verification & prerequisites — who may run the flow and which slots must be filled (§1–§2); summarized here per module.
Type 3 L1 automation & ticketing — tool reads/writes, reply shape, and when tickets open; humans own ticket resolution.

§3.1 is the at-a-glance matrix for all modules; §7 is the detailed breakdown.

7.1 ORDER_STATUS — Order status

Type 1 — Policy & messaging (vendor questionnaire)

# Question shared_field_id
OS1 Normal processing time before shipment? sf_processing_time_before_ship
OS2 Proactive status updates (if any)? (optional sf_order_status_proactive_updates)
OS3 If delayed before shipment, what do you tell the customer? sf_major_delay_communication
OS4 Ship to / do not ship to? sf_shipping_regions_served, sf_shipping_regions_excluded
OS5 Order # help + checklist sf_order_id_help, sf_first_message_checklist

Type 2 — Verification & prerequisites

  • Email: From = order email; multi-order disambiguation (§1.1).
  • Widget: email + OTP + session TTL (§1.2).
  • Slots: order_id (or pick from candidate list).

Type 3 — L1 automation & ticketing

  • L1: Read order / fulfillment from DB after Type 2 passes; compose reply with Type 1 messaging.
  • Ticket: Data missing, anomaly, or outside playbook → create ticket (no full auto-resolution).

7.2 INVENTORY_STOCK — Inventory / stock

Type 1 — Policy & messaging (vendor questionnaire)

# Question shared_field_id
IV1–IV5 (unchanged — back-in-stock, pre-order, discontinued, in-store vs online, disclaimer) sf_back_in_stock_policy, sf_preorder_policy, sf_discontinued_product_policy, sf_instore_vs_online_inventory, optional disclaimer

Type 2 — Verification & prerequisites

  • Slots: product_name / SKU (and disambiguation if many matches).
  • Widget: May allow anonymous stock checks, or require OTP session if tied to “my order” — product decision.

Type 3 — L1 automation & ticketing

  • L1: Inventory tool read from DB; blend Type 1 policy snippets where relevant.
  • Ticket / clarify: Heavy disambiguation or conflicting data → ask clarifying questions or ticket.

7.3 FAQ — General FAQ (includes refund policy, not refund status)

Type 1 — Policy & messaging (vendor questionnaire)

# Question shared_field_id
FQ1–FQ8 Shipping, returns, refunds policy summary, payment, promo, tax, contact, policy links (as in prior doc)

Type 2 — Verification & prerequisites

  • None for anonymous FAQ-only path on the widget (§1.2).

Type 3 — L1 automation & ticketing

  • L1: RAG / structured FAQ from Type 1 (+ ALL where useful).
  • Escalation: Out of scope → suggest email or ticket per vendor channels (sf_support_channels).

7.4 ORDER_CANCEL — Order cancellation

Type 1 — Policy & messaging (vendor questionnaire)

# Question shared_field_id
CX1–CX5 Window, how to request, next step if impossible, pre-order, refund timing sf_cancellation_*, sf_refund_*, sf_order_change_not_possible_next_step

Type 2 — Verification & prerequisites

  • Same order-scoped verification as ORDER_STATUS (§1, §2).

Type 3 — L1 automation & ticketing

  • L1: Eligibility + cancel when rules/DB allow; otherwise explain from Type 1.
  • Ticket: Ambiguous, edge case, or cancel not permitted by rules → open ticket if policy requires human judgment.

7.5 HUMAN_ESCALATION

Type 1 — Policy & messaging (vendor questionnaire)

# Question shared_field_id
HE1–HE4 When to ask human, channels, SLA, checklist sf_human_escalation_when, sf_support_*, sf_first_message_checklist

Type 2 — Verification & prerequisites

  • Minimal — optional context slots only; no order read required unless combined with another intent.

Type 3 — L1 automation & ticketing

  • L1: Ack + routing copy from Type 1 / ALL.
  • Ticket: Create ticket when vendor policy or product rules say so.

7.6 COMPLAINT — Ticket-led, strict verification

Type 1 — Policy & messaging (vendor questionnaire)

# Question shared_field_id
CP1–CP6 Ack, SLA, supervisor, remedies summary, abuse policy, channels sf_complaint_*, sf_wrong_item_remedies, sf_refund_methods, sf_support_channels

Type 2 — Verification & prerequisites

  • Strict same as other fiber flows: email alignment or widget OTP session; attach order when relevant.

Type 3 — L1 automation & ticketing

  • L1: Empathetic ack + Type 1 snippets + severity / structured intake.
  • Ticket: Always create ticket; human resolves.

7.7 ORDER_SUMMARY

Type 1 — Policy & messaging (vendor questionnaire)

# Question shared_field_id
SM1–SM4 Receipt naming, tax invoice note, checklist, order # help optional receipt naming, sf_order_summary_tax_invoice_note, sf_first_message_checklist, sf_order_id_help

Type 2 — Verification & prerequisites

  • Same as ORDER_STATUS (order-scoped).

Type 3 — L1 automation & ticketing

  • L1: Read line items / totals from DB; compose recap + Type 1 (tax/invoice disclaimers).
  • Ticket: Tax/invoice edge cases per vendor policy → human.

7.8 REFUND_STATUS — Transactional (distinct from FAQ refund policy)

Type 1 — Policy & messaging (vendor questionnaire)

# Question shared_field_id
RF1–RF6 Methods, timeline, after return received, partial rules, store credit, delay messaging sf_refund_*, optional sf_refund_after_return_received, sf_refund_delay_exception

Type 2 — Verification & prerequisites

  • Verified identity + order / return reference (slots as your schema defines).

Type 3 — L1 automation & ticketing

  • L1: Read refund/return pipeline state from DB when modeled; answer with Type 1 timelines where applicable.
  • Ticket: State not in DB or ambiguous → ack + ticket after verification.

7.9 SHIPPING_TRACKING

Type 1 — Policy & messaging (vendor questionnaire)

# Question shared_field_id
ST1–ST6 Carriers, methods, cost, cutoff, regions, customs (as before)

Type 2 — Verification & prerequisites

  • Same as ORDER_STATUS (verified order).

Type 3 — L1 automation & ticketing

  • L1: Read tracking fields for that order; reply with snapshot + Type 1 carrier/transit copy.
  • Ticket: Carrier claim / dispute → open ticket for human.

7.10 WRONG_ITEM — Ticket-led

Type 1 — Policy & messaging (vendor questionnaire)

# Question shared_field_id
WI1–WI6 Deadline, evidence, remedies, damage explanation, return shipping, links sf_wrong_item_*, sf_return_shipping_payer, sf_policy_link_returns, sf_how_to_start_return

Type 2 — Verification & prerequisites

  • Order-scoped verification + issue_type slot; email may include photo attachments.

Type 3 — L1 automation & ticketing

  • L1: Ack + Type 1 policy + structured fields for the ticket body.
  • Ticket: Create ticket; human executes reship/refund/return.

7.11 RETURN_EXCHANGE — Ticket-led initiation

Type 1 — Policy & messaging (vendor questionnaire)

# Question shared_field_id
RE1–RE6 Window, condition, non-returnable, shipping, exchange, refund timing sf_return_*, sf_exchange_policy, sf_how_to_start_return, sf_refund_*

Type 2 — Verification & prerequisites

  • Order-scoped verification + optional reason / return intent slot.

Type 3 — L1 automation & ticketing

  • L1: Policy in reply from Type 1 + open ticket (or portal link if product adds it).
  • Ticket: Human / ops fulfills RMA.

7.12 NOT_RECEIVED_MARKED_DELIVERED — Ticket-led (replaces vague “delivery problem”)

Type 1 — Policy & messaging (vendor questionnaire)

# Question shared_field_id
NR1 “Delivered” but not received — customer steps, wait time, claim sf_delivered_not_received_policy
NR2 Carrier / claim expectations sf_carriers_and_tracking_policy

Type 2 — Verification & prerequisites

  • Order-scoped verification (same pattern as ORDER_STATUS).

Type 3 — L1 automation & ticketing

  • L1: Last tracking snapshot + Type 1 snippet → then always open ticket for investigation.
  • Ticket: Human handles carrier / claim (§0.1).

7.13 SHIPMENT_STUCK_OR_DELAYED — Ticket-led

Type 1 — Policy & messaging (vendor questionnaire)

# Question shared_field_id
SD1 When shipment seems stuck or far past expected range, what should customer do first? sf_stuck_shipment_customer_steps
SD2 How you communicate major delays sf_major_delay_communication
SD3 Carriers reference sf_carriers_and_tracking_policy

Type 2 — Verification & prerequisites

  • Order-scoped verification.

Type 3 — L1 automation & ticketing

  • L1: Last scan dates + Type 1 → open ticket for human carrier/ops follow-up.

7.14 PAYMENT_PROBLEM — Ticket-led (prerequisites vary)

Type 1 — Policy & messaging (vendor questionnaire)

# Question shared_field_id
PP1–PP6 Payment methods, failed payment, double charge intake, promo, tax, price adjust sf_payment_methods_accepted, sf_failed_payment_guidance, sf_double_charge_intake, sf_promo_discount_rules, sf_tax_display_policy, sf_price_adjustment_policy

Type 2 — Verification & prerequisites

  • Order-scoped issues: verified identity + order id.
  • Pre-purchase / checkout failures: may only have email + narrative → ticket with available slots.

Type 3 — L1 automation & ticketing

  • L1: Structured intake + ticket; no automated money movement.
  • Ticket: Human + finance tools.

7.15 ORDER_CHANGE — Ticket-led only

Type 1 — Policy & messaging (vendor questionnaire)

# Question shared_field_id
OC1–OC4 Until when changes are sometimes possible, how to request, impossible case, cancel alternative sf_order_change_*, sf_cancellation_*

Type 2 — Verification & prerequisites

  • Order-scoped verification + capture requested change (address/items/qty — slots).

Type 3 — L1 automation & ticketing

  • L1 v1: No auto-mutate order — ack + open ticket only.
  • Ticket: Human decides feasible vs offer cancel path from Type 1.

7.16 WARRANTY — Ticket-led

Type 1 — Policy & messaging (vendor questionnaire)

# Question shared_field_id
WA1–WA5 Scope, voiders, process, timeline optional, escalation sf_warranty_*, sf_complaint_supervisor_escalation

Type 2 — Verification & prerequisites

  • Verified identity + proof-of-purchase / order reference.

Type 3 — L1 automation & ticketing

  • L1: Intake + Type 1 + ticket.
  • Ticket: Human adjudicates.

7.17 PRODUCT_FIT

Type 1 — Policy & messaging (vendor questionnaire)

# Question shared_field_id
PF1–PF4 Sizing, compatibility, materials, human edge cases sf_sizing_fit_guidance, sf_compatibility_notes, sf_materials_care_limitations, sf_human_escalation_when

Type 2 — Verification & prerequisites

  • Optional product slot (name/SKU) for specificity; no order required for pure fit FAQ.

Type 3 — L1 automation & ticketing

  • L1: KB + optional CATEGORY_METADETAILS tools when enabled (§7.20).
  • Ticket / human: Edge cases per sf_human_escalation_when.

7.18 STORE_LOCAL

Type 1 — Policy & messaging (vendor questionnaire)

# Question shared_field_id
SL1–SL4 Locations, pickup, inventory nuance, local returns sf_physical_locations_hours, sf_pickup_rules, sf_instore_vs_online_inventory, sf_how_to_start_return

Type 2 — Verification & prerequisites

  • None for typical Knowledge replies.

Type 3 — L1 automation & ticketing

  • L1: KB-only from Type 1; no order tools required.

7.19 FEEDBACK

Type 1 — Policy & messaging (vendor questionnaire)

# Question shared_field_id
FB1–FB3 CSAT process, negative follow-up optional, tone sf_feedback_csat_process, optional negative follow-up, sf_tone_and_words_to_avoid

Type 2 — Verification & prerequisites

  • Optional link to prior ticket / context if product supports it.

Type 3 — L1 automation & ticketing

  • L1: CSAT link / one-shot ask per Type 1.
  • Human: Negative follow-up path if configured.

7.20 CATEGORY_METADETAILS — Category metadetails (store-wide, DB via tools)

This module is special: there is no Type 1 questionnaire — only a store-level enable/disable (see below). Policy copy for when to prefer PDP vs human still lives in PRODUCT_FIT / FAQ.

Type 1 — Policy & messaging (vendor questionnaire)

  • None. Vendor configuration: one toggle only — Enabled or Disabled for the store. No per-category or per-product granularity in v1.

Type 2 — Verification & prerequisites

  • Vendor enables the feature; sync pipeline persists category metadetails in DB.
  • Slots: resolve product → category (e.g. name/SKU → category) before tool calls; tools return fields, not guesses.

Type 3 — L1 automation & ticketing

When enabled

  • L1 may invoke tool calls to read category metadetails (and related synced fields — exact schema in engineering doc).
  • Coverage: all products in synced categories (e.g. sizing, materials, care, compatibility at category level).

When disabled

  • Do not call category-metadetails tools for customer-facing answers.
  • Fall back to PRODUCT_FIT / FAQ, PDP links, or escalation.

Ticketing

  • If data missing, disabled, or intent unclear → ticket or clarify per ALL / PRODUCT_FIT.

8. L1 agentic implementation checklist (engineering)

8.1 Core services

  • Intent router → module + pillar (K / T / X / catalog-metadata) — use your module/enum names if they differ from this doc.
  • Tool-call layer (or RPC): explicit functions that query the database for each concern — orders, line items, fulfillment/tracking, inventory, refund/return state, products, categories, category metadetails — using real table/field names from your schema (not necessarily any placeholder names in this plan). The LLM/agent must only assert facts returned by tools (plus vendor KB where allowed).
  • Slot extractor (per module manifest): order_id, product_name, issue_subtype, etc.
  • Email adapter: from_email + thread id; enforce same-email rule for T/X.
  • Widget adapter: session + OTP service + TTL (e.g. 1h).
  • DB readers (exposed as tools) for order, fulfillment, tracking, inventory, refund state (as available in your schema).
  • Category metadetails tools: e.g. resolve product_id/sku → category_id → fetch metadetails record; respect vendor CATEGORY_METADETAILS enabled flag before calling.
  • Writers only where allowed (e.g. cancel); ticket creator for all X modules.

8.2 Manifests (per module)

  • Map each module to §2.4: Type 1 = which shared_field_id keys feed prompts; Type 2 = verification_gate + required_slots; Type 3 = l1_actions[], ticket triggers, tool allowlist.
  • required_slots, verification_gate, pillar, l1_actions[], ticket_template_id (for X).
  • Disambiguation rule when multiple orders match email.

8.3 Knowledge

  • Vendor shared_field_id storage + sync.
  • RAG/chunking with module_code metadata for K paths.
  • Store-level flag: category_metadetails_enabled (boolean) — gates category-metadetails tool calls only; no per-category flags in v1.

8.4 Safety

  • No existence leak: wrong email must not confirm others’ orders.
  • Rate limits on OTP and lookups.
  • Guardrails (existing) before LLM.

8.5 Explicit non-goals (this phase)

  • No Shopify OAuth login for customers.
  • No magic links.
  • No full automated ticket resolution workflow — humans own tickets.

9. Optional shared_field_id backlog

  • sf_order_status_proactive_updates
  • sf_inventory_disclaimer
  • sf_receipt_naming
  • sf_refund_after_return_received
  • sf_refund_delay_exception
  • sf_negative_feedback_escalation

End of document.