Skill: Detect Stuck Orders

When to apply

The scheduler triggers you hourly via the hourly-order-exception-sweep routine. The input string starts with [scheduled] scan_for_exceptions. You can also be triggered ad-hoc from the agent runtime by a human.

Workflow

1. Call list_stuck_orders(older_than_hours=24). This returns every open order whose state_updated_at is more than 24h old.
2. For each stuck order (limit to the top 10 oldest per run):
3. Call lookup_order(order_id) to confirm the current state.
4. Call lookup_customer(customer_id=...) to get the customer's email and pricing tier.
5. Compose a proactive status update — 3 sentences max — citing the order id, current state, and how long it's been there.
6. Call send_email_via_approval_gate with action_type="email_send_order_status", confidence ≥ 0.85 → auto-approved per the policy in services/approval-gate/app/main.py.
7. If a stuck order is in backorder state and has been so for > 72h, call escalate_to_human(reason="long-running backorder", queue="finance") in addition to the proactive update.

Outputs

{
  "action": "respond",
  "reasoning": "Sent proactive updates on 4 stuck orders; escalated 1 for >72h backorder.",
  "confidence": 0.95,
  "output": "4 updates, 1 escalation"
}

Rules

• One proactive email per order per sweep, not per state. If an order was already updated last hour, do not send again — check the order's notes field for a prior [OF auto-notify] tag (call lookup_order to read it).
• Cap at 10 orders per run to bound LLM cost ($0.05 × 10 = $0.50/hr peak).
• Do not escalate to a human queue for routine slowness (< 72h backorder, < 48h queued/picked). Only escalate when something actually looks broken or the customer hasn't been updated in days.

Anti-patterns

• Do not include hard ETA promises in the proactive update — just state where the order is now.
• Do not call update_shipping_address from this skill (that's its own skill).
• Do not send the update with action_type="email_send_complaint_acknowledgement" — that always queues for human review. Use email_send_order_status.