route-readiness-call

Route Readiness Call

Use this skill when a delivery rider is already on the route and an upcoming customer's readiness would change the order of the remaining stops. It is the reusable core of the RouteReady app in this repository (apps/typescript/routeready): which stop to call, the call task, the result schema, the evidence gate, and the rules that turn an answer into a routing constraint.

When To Use

• A rider is on a multi-stop delivery or service route and the next stops are 6 to 45 minutes away
• The customer gave this phone number for contact about this delivery, and the operator is authorised to call about the order
• The output should be a verified readiness answer that a route optimiser or a dispatcher can act on

When Not To Use

• Marketing, collections, surveys, or anything other than the delivery the customer is expecting
• Stops the rider will reach in under 6 minutes: a call takes about two minutes and the route cannot adapt in time
• A second call to the same customer on the same day, or a retry after an unclear or ambiguous call
• Emergency, medical, legal or financial conversations
• Destinations CALL-E does not currently accept (see references/safety.md)

Required Inputs

• run_id, stop_id: stable identities; the idempotency key is routeready:{run_id}:{stop_id}
• merchant, order_ref
• phone_e164, region (ISO country code), language
• eta_minutes: minutes until the rider arrives, exactly as the customer will be told
• cod_amount: amount due at the door with its currency, or null when prepaid
• authorization_confirmed: the operator confirms the number was given for delivery contact

Picking The Call

There is one line, so only one call may be in flight. Among stops not called today whose projected arrival is 6 to 45 minutes away, call the soonest. Skip the stop the rider is already driving to.

"Called today" is decided by destination number, not by stop: skip a number already called today, even from another stop, route or restarted day, unless a person explicitly approved a repeat call for a different reason. Record the number when the call is attempted, before the create request, so an ambiguous creation counts as today's call.