> ## Documentation Index
> Fetch the complete documentation index at: https://docs.duckie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Intake and Order Context

> Normalize customer WISMO requests and backend events into a consistent case context

WISMO quality depends on the context Duckie has before it responds. The intake layer should create or update a stable WISMO case, identify the order, and build a canonical context object that downstream workflows and agents can trust.

## Entry Points

| Entry point     | Typical trigger                                                            | First action                                                             |
| --------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Customer ticket | New ticket, public reply, or WISMO tag                                     | Identify customer and likely order.                                      |
| Chat message    | Authenticated chat or widget intent                                        | Use session identity and recent order data first.                        |
| Email reply     | Customer replies to an existing thread                                     | Reuse the existing WISMO case and order if possible.                     |
| OMS event       | Order status, hold, cancellation, or fulfillment change                    | Find existing case or create proactive monitoring state.                 |
| WMS event       | Pick, pack, short-pick, label, or handoff update                           | Update fulfillment state and decide whether a customer update is needed. |
| Supplier event  | ETA, allocation, stockout, or inbound receiving update                     | Route to supplier backorder handling or proactive monitor.               |
| Carrier event   | Scan, no movement, delivery attempt, return-to-sender, or delivered update | Route to carrier handling or proactive monitor.                          |
| Scheduled sweep | Follow-up due, stale tracking, or missed webhook check                     | Rehydrate the WISMO case and compare current status to last update.      |

## Intake Contract

Every WISMO run should produce a structured case object before it routes to a specialist:

| Field                     | Purpose                                                                         |
| ------------------------- | ------------------------------------------------------------------------------- |
| `wismo_case_id`           | Stable key for the customer/order issue.                                        |
| `source_channel`          | Ticket, chat, email, webhook, or scheduler.                                     |
| `customer_id`             | Customer identity from authenticated context, ticket metadata, or lookup.       |
| `order_id`                | Target order. Ask for this only when multiple orders are plausible.             |
| `shipment_ids`            | Shipment groups attached to the order.                                          |
| `ticket_id`               | Active support conversation, if one exists.                                     |
| `prior_contact_count`     | Number of WISMO contacts for the same order.                                    |
| `last_customer_update_at` | Most recent public status message to the customer.                              |
| `last_status_sent`        | Status facts already communicated.                                              |
| `next_follow_up_due_at`   | Promised next checkpoint, if any.                                               |
| `restricted_state`        | Fraud, payment, address, legal, VIP, high-value, or confidence guardrail flags. |

## Order Context Workflow

Build order context in a repeatable order. This keeps the downstream agents focused on interpretation instead of basic data plumbing.

```mermaid theme={null}
flowchart TD
  Start["Start WISMO run"]
  Customer["Lookup customer"]
  Orders["Find candidate orders"]
  Select{"One clear order?"}
  Ask["Ask for order number or verification"]
  OMS["Lookup OMS order detail"]
  Shipments["Lookup shipments"]
  WMS["Lookup WMS fulfillment state"]
  Inventory["Lookup inventory and allocation"]
  Supplier["Lookup supplier status"]
  Carrier["Lookup carrier tracking"]
  History["Lookup support history"]
  Save["Save canonical order context"]
  Next["Route to investigation or condition routing"]

  Start --> Customer --> Orders --> Select
  Select -->|No| Ask --> Orders
  Select -->|Yes| OMS --> Shipments --> WMS --> Inventory --> Supplier --> Carrier --> History --> Save --> Next
```

## Required Context

| Source           | Minimum fields                                                                                                             |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Customer profile | Customer ID, email, customer tier, contact preferences, risk-safe flags.                                                   |
| OMS              | Order status, order date, promised ship date, promised delivery date, payment state, hold state, cancellation eligibility. |
| Order items      | SKU, quantity, item value, item status, shipment mapping, replacement/refund eligibility.                                  |
| WMS              | Pick status, pack status, short-pick status, label state, handoff confirmation, warehouse queue.                           |
| Inventory        | On-hand, reserved, inbound, allocation state, approved substitute availability.                                            |
| Supplier         | Purchase order, supplier ETA, allocation note, inbound receiving state, ETA confidence.                                    |
| Carrier          | Tracking number, carrier status, latest scan, exception reason, ETA, proof of delivery, investigation status.              |
| Support history  | Prior contacts, previous customer promises, internal notes, escalation status, open tickets.                               |

## When to Use an Investigation Agent

Call the order investigation agent when:

* OMS says shipped but WMS has no handoff confirmation
* Carrier tracking has a label but no first physical scan
* Inventory shows stock but allocation failed
* Supplier ETA and promised customer date conflict
* Multiple shipments contain overlapping or missing items
* The customer references an order that does not match account data
* The support history contains a newer human update than backend data

The investigation agent should return:

* Current best understanding of the order state
* Conflicting facts, if any
* Recommended WISMO condition
* Customer-safe facts
* Internal-only facts that must not be shown to the customer
* Recommended next action and confidence

## Guardrails

* Do not ask for an order number if authenticated metadata identifies one clear order.
* Do not expose fraud, payment-risk, supplier blame, margin, or internal allocation notes to customers.
* Do not proceed to a customer-visible answer when customer identity is ambiguous.
* Do not treat "label created" as carrier possession unless handoff or first scan is confirmed.
* Do not overwrite a newer human reply with an older backend status.

## Next Pages

After intake and context:

1. Build [condition routing and agents](/examples/wismo-order-status/condition-routing-and-agents).
2. Add [proactive follow-up](/examples/wismo-order-status/proactive-follow-up).
3. Add [escalation and resolution](/examples/wismo-order-status/escalation-and-resolution) for guarded cases.