rsc-universal 0.1.1

package/skills/llm-pipeline/evals/cases.yaml

@@ -0,0 +1,44 @@
+skill: llm-pipeline
+
+should_trigger:
+  - prompt: "Chain three LLM calls: extract entities, then summarize, then classify — and make it not fall over."
+    why: "Canonical multi-step orchestration with data flowing between steps plus a reliability requirement — the core of this skill."
+  - prompt: "We keep getting random 429s and timeouts from OpenAI and it takes our feature down. Add fallbacks."
+    why: "Reliability layer: router fallback, retries, circuit-breaking around provider failures."
+  - prompt: "Put a gateway in front of OpenAI and Claude so we can swap models and load-balance."
+    why: "LLM gateway/router (LiteLLM) is the central tool of the skill."
+  - prompt: "Our LLM bill tripled — we call the model fresh on every request even for repeats."
+    why: "Non-obvious: framed as a cost problem, but the real fix is caching + tier routing, which are this skill's controls (not pure accounting)."
+  - prompt: "Necessito encadenar crides a l'LLM amb fallback i cachejar les respostes."
+    why: "Catalan phrasing for chaining + fallback + caching — exactly this skill, in another language."
+  - prompt: "Route easy requests to Haiku and only escalate to Opus when confidence is low."
+    why: "Model-tier routing, cheap-first with escalation, is the standard cost lever here."
+
+should_not_trigger:
+  - prompt: "Help me write a better system prompt and few-shot examples for this classification task."
+    route_to: prompt-engineering
+    why: "This is prompt wording, not the orchestration around prompts."
+  - prompt: "Make this single call return JSON matching my Pydantic schema."
+    route_to: structured-extraction
+    why: "One schema-bound call, not a chain — this skill uses structured output as a contract but does not own single extraction."
+  - prompt: "Chunk my docs, embed them, and retrieve relevant context for the prompt."
+    route_to: rag
+    why: "Building a retriever is retrieval, not call-chaining; a pipeline may call a retriever as a step but does not build it."
+  - prompt: "Build an agent that decides which tools to call to book travel."
+    route_to: building-agents
+    why: "An autonomous decision loop where the model picks its next step — not a fixed DAG you designed."
+  - prompt: "Build me a dashboard attributing our monthly AI spend per team."
+    route_to: cost-tracking
+    why: "Spend ledger and reporting, not the pipeline controls (tiers, caching, abort caps) this skill owns."
+
+capability:
+  - scenario: "Design a production pipeline that classifies an inbound support ticket, then drafts a reply, behind a router with fallback, with caching and a per-request cost cap."
+    must_include:
+      - "Typed/structured-output contract between the classify step and the draft step (validated at the seam)"
+      - "Explicit timeout on every LLM call (30-60s)"
+      - "Bounded retries with exponential backoff + jitter, never an unbounded loop"
+      - "Router with a fallback model, and mention of content_policy / context_window fallback buckets"
+      - "Prefix cache enabled (stable prefix first); semantic cache only if safe with a strong embedder + tuned threshold"
+      - "Model-tier routing cheap-first (e.g. Haiku then escalate), and a per-request budget cap that ABORTS"
+      - "Per-step observability fields: model, tokens, cost, latency_ms, cache_hit, fallback_used, retry_count"
+      - "Note that schema-valid does not mean correct; defer quality measurement to agent-eval"

package/skills/llm-pipeline/references/caching-layers.md

@@ -0,0 +1,60 @@
+# Caching layers: prefix vs semantic
+
+Two caches, different mechanisms, different risk profiles. Do not conflate them.
+
+## Layer 1 — prefix / prompt cache (provider-native)
+
+Matches an **exact prefix** of your prompt at the provider and reuses the cached compute. Transparent and safe: identical input → identical cached state. Free upside, no correctness risk.
+
+**OpenAI** — automatic, on by default, ~50% off cached input tokens. No write penalty, no storage fee. First request full price; subsequent prefix hits half price.
+
+**Anthropic** — explicit: you mark cache breakpoints (`cache_control`). Deeper discount:
+
+| Operation | Multiplier vs base input |
+| --- | --- |
+| Cache read | 0.1× (~90% off) |
+| 5-minute cache write | 1.25× |
+| 1-hour cache write | 2× |
+
+On long, stable prefixes this is ~90% cost and ~85% latency reduction.
+
+### Order prompts for maximum prefix hits
+
+Put content **most stable first, most variable last**:
+
+1. System prompt / role instructions (never changes)
+2. Fixed reference context, tool definitions, few-shot exemplars (changes rarely)
+3. Retrieved/dynamic context (changes per request)
+4. The user's actual turn (changes every time)
+
+If you put the user's variable input first, the prefix never matches and you cache nothing. For Anthropic, set the breakpoint at the end of the stable block (1–2).
+
+## Layer 2 — semantic cache (your gateway)
+
+Embeds the incoming query, looks up an **embedding-similar prior query**, and returns *that prior response*. Lives in your gateway: GPTCache, a Redis vector store, Bifrost, etc.
+
+The danger: it returns a **different** prior answer for a **similar** query. Quality is dominated by the embedding model — a weak embedder yields **false cache hits**, i.e. a confidently wrong answer to a question that only looked similar (GPTCache is documented returning incorrect saved responses for similar prompts; cf. Microsoft GenCache, NeurIPS 2025).
+
+### Enable it only when all hold
+
+- Queries are paraphrase-heavy (FAQ, support, repeated intents).
+- An approximate / near-match answer is acceptable for the use case.
+- It is **not** a correctness-critical path (no legal, medical, financial, or contract logic).
+
+### Tuning
+
+- **Embedding model:** use a strong, current embedder. The cheap default is where false hits come from.
+- **Similarity threshold:** start strict (e.g. cosine ≥ 0.95) and loosen only with eval data on real query pairs. Too loose = false hits; too strict = no hits.
+- **TTL:** short for time-sensitive answers (prices, status), longer for stable knowledge. Stale-but-confident is its own failure mode.
+- **Scope keys:** namespace the cache by tenant/locale/model so you never serve tenant A's answer to tenant B.
+
+## Multi-tier order
+
+Check caches cheapest-and-safest first, fall through to inference:
+
+```text
+semantic cache  ->  prefix cache  ->  live inference
+   (gateway)        (provider)         (full price)
+```
+
+Only reach inference on a miss. But if correctness matters more than cost, drop the semantic tier entirely and rely on prefix cache + inference — prefix cache never changes the answer.

package/skills/llm-pipeline/references/litellm-router.md

@@ -0,0 +1,101 @@
+# LiteLLM Router / Proxy config (v1.83.x)
+
+Fuller config than the SKILL body. Version-pinned to the **v1.83.3-stable** line (also recent: v1.81.9-stable, v1.81.13). LiteLLM exposes a unified OpenAI-format `completion()` across 100+ providers, with retry/fallback, cost tracking, and budget management, as an SDK or a Proxy Server.
+
+## SDK Router with every fallback bucket
+
+```python
+from litellm import Router
+
+router = Router(
+    model_list=[
+        {"model_name": "smart",
+         "litellm_params": {"model": "anthropic/claude-sonnet-4-6",
+                            "api_key": "os.environ/ANTHROPIC_API_KEY",
+                            "timeout": 30, "order": 1}},
+        {"model_name": "smart",          # same group, order 2 = first internal fallback
+         "litellm_params": {"model": "openai/gpt-4o",
+                            "api_key": "os.environ/OPENAI_API_KEY",
+                            "timeout": 30, "order": 2}},
+        {"model_name": "cheap",
+         "litellm_params": {"model": "anthropic/claude-haiku-4-5",
+                            "api_key": "os.environ/ANTHROPIC_API_KEY",
+                            "timeout": 20}},
+        {"model_name": "long-ctx",
+         "litellm_params": {"model": "openai/gpt-4o",
+                            "api_key": "os.environ/OPENAI_API_KEY", "timeout": 60}},
+    ],
+    # cross-group fallbacks (after order levels in a group are exhausted)
+    fallbacks=[{"smart": ["cheap"]}],
+    content_policy_fallbacks=[{"smart": ["smart"]}],   # ContentPolicyViolationError
+    context_window_fallbacks=[{"smart": ["long-ctx"]}],# ContextWindowExceededError
+    default_fallbacks=["cheap"],                         # catch-all last resort
+    num_retries=2,            # bounded retries PER order level
+    timeout=30,              # router-wide hard cap
+    retry_after=1,
+)
+```
+
+Order semantics: a request to an `order=1` deployment that fails (connection error, 404, 429, ...) auto-tries `order=2`, then `order=3`. Each order level runs its own `num_retries` before escalating. Once all orders in the group are exhausted, the `fallbacks`/specialized buckets fire. Retry backoff is exponential from `INITIAL_RETRY_DELAY` 0.2s up to `MAX_RETRY_DELAY` 10s, with jitter.
+
+## Keys come from env, never inline
+
+Use `os.environ/VAR` indirection (proxy YAML) or read `os.environ[...]` in SDK. A literal `sk-...` in a model_list is a leaked credential and a verify.sh FAIL.
+
+## Proxy Server config (config.yaml)
+
+```yaml
+model_list:
+  - model_name: smart
+    litellm_params:
+      model: anthropic/claude-sonnet-4-6
+      api_key: os.environ/ANTHROPIC_API_KEY
+      timeout: 30
+  - model_name: smart-backup
+    litellm_params:
+      model: openai/gpt-4o
+      api_key: os.environ/OPENAI_API_KEY
+      timeout: 30
+
+router_settings:
+  num_retries: 2
+  timeout: 30
+  fallbacks: [{"smart": ["smart-backup"]}]
+  context_window_fallbacks: [{"smart": ["smart-backup"]}]
+
+litellm_settings:
+  cache: true
+  cache_params:
+    type: redis
+    host: os.environ/REDIS_HOST
+    port: os.environ/REDIS_PORT
+    ttl: 600
+```
+
+## Budget & rate limits
+
+```yaml
+litellm_settings:
+  max_budget: 100         # $ hard cap across the proxy; aborts over-budget requests
+  budget_duration: 30d
+general_settings:
+  master_key: os.environ/LITELLM_MASTER_KEY
+```
+
+Per-key / per-tenant budgets are set on virtual keys (`/key/generate` with `max_budget` and `tpm_limit`/`rpm_limit`). Budgets that ABORT are the point — a logged-only budget does not stop a runaway loop.
+
+## Cost callback
+
+```python
+import litellm
+
+def track(kwargs, response, start, end):
+    cost = kwargs.get("response_cost")
+    # emit per-step: model, tokens, cost, latency, cache_hit, fallback used
+    log.info("llm_call", model=kwargs["model"], cost=cost,
+             latency_ms=(end - start).total_seconds() * 1000)
+
+litellm.success_callback = [track]
+```
+
+The cost/latency numbers belong in your observability backbone; attribution dashboards belong to the cost-tracking skill, not here.

package/skills/llm-pipeline/scripts/verify.sh

@@ -0,0 +1,169 @@
+#!/usr/bin/env bash
+# verify.sh — static, read-only checks for an llm-pipeline artifact (gateway/router
+# config or typed-chain code). No live API calls. Offline and deterministic.
+#
+# Usage: verify.sh [PATH]   (PATH = file or dir; defaults to current directory)
+# Exits 0 when every applicable check passes (including an empty/clean target),
+# non-zero when any check FAILs. Checks that do not apply to the artifacts present
+# are SKIPped, never failed.
+
+set -u
+
+TARGET="${1:-.}"
+
+if [[ ! -e "$TARGET" ]]; then
+  echo "verify.sh: path not found: $TARGET" >&2
+  exit 2
+fi
+
+fail_count=0
+pass() { printf 'PASS  %s\n' "$1"; }
+fail() { printf 'FAIL  %s\n' "$1"; fail_count=$((fail_count + 1)); }
+skip() { printf 'SKIP  %s\n' "$1"; }
+
+# Collect candidate source and config files (read-only). Portable to bash 3.2
+# (macOS default) — no mapfile, newline-delimited via a temp array build.
+CODE_FILES=(); YAML_FILES=(); JSON_FILES=()
+while IFS= read -r f; do [[ -n "$f" ]] && CODE_FILES+=("$f"); done < <(find "$TARGET" -type f \( -name '*.py' -o -name '*.ts' -o -name '*.js' \) 2>/dev/null)
+while IFS= read -r f; do [[ -n "$f" ]] && YAML_FILES+=("$f"); done < <(find "$TARGET" -type f \( -name '*.yaml' -o -name '*.yml' \) 2>/dev/null)
+while IFS= read -r f; do [[ -n "$f" ]] && JSON_FILES+=("$f"); done < <(find "$TARGET" -type f -name '*.json' 2>/dev/null)
+ALL_FILES=("${CODE_FILES[@]+"${CODE_FILES[@]}"}" "${YAML_FILES[@]+"${YAML_FILES[@]}"}" "${JSON_FILES[@]+"${JSON_FILES[@]}"}")
+
+if [[ ${#ALL_FILES[@]} -eq 0 ]]; then
+  echo "verify.sh: no .py/.ts/.js/.yaml/.yml/.json files under $TARGET — nothing to check."
+  exit 0
+fi
+
+# grep helper across a file list; prints "file:line:match" lines, empty if none.
+grep_files() { # $1 = pattern, rest = files
+  local pat="$1"; shift
+  [[ $# -eq 0 ]] && return 0
+  grep -HInE "$pat" "$@" 2>/dev/null   # -H so the filename prefix is always present
+}
+
+# --- Check 1: no hardcoded provider keys (always applicable) ---------------
+KEY_HITS="$(grep_files '(sk-[A-Za-z0-9_-]{16,}|sk-ant-[A-Za-z0-9_-]{16,})' "${ALL_FILES[@]}")"
+if [[ -n "$KEY_HITS" ]]; then
+  fail "no hardcoded API keys (found literal key(s); use env vars)"
+  echo "$KEY_HITS" | sed 's/^/      /'
+else
+  pass "no hardcoded API keys"
+fi
+
+# --- Check 2: every completion/chat call site sets a timeout ---------------
+# A "call site" line invokes completion(/chat.completions.create/responses.create.
+CALL_PAT='(\.completion\(|chat\.completions\.create\(|responses\.(create|parse)\()'
+CALL_HITS="$(grep_files "$CALL_PAT" "${CODE_FILES[@]+"${CODE_FILES[@]}"}")"
+if [[ -z "$CALL_HITS" ]]; then
+  skip "timeout on every call (no LLM call sites found)"
+else
+  # A call line is OK if it (or a nearby Router/client default) sets timeout.
+  # Heuristic, read-only: flag call lines on which 'timeout' does not appear AND
+  # whose file has no router/client-level timeout default.
+  unbounded=""
+  while IFS= read -r line; do
+    file="${line%%:*}"
+    if echo "$line" | grep -qE 'timeout'; then continue; fi
+    # allow a router/client default timeout in the same file
+    if grep -qE 'timeout[[:space:]]*[:=]' "$file" 2>/dev/null; then continue; fi
+    unbounded+="$line"$'\n'
+  done <<< "$CALL_HITS"
+  if [[ -n "${unbounded//[$'\n']/}" ]]; then
+    fail "timeout on every call (call site(s) with no timeout)"
+    printf '%s' "$unbounded" | sed '/^$/d;s/^/      /'
+  else
+    pass "timeout on every call"
+  fi
+fi
+
+# --- Check 3: retries are bounded (no while True retry loops) --------------
+LOOP_HITS="$(grep_files 'while[[:space:]]+True' "${CODE_FILES[@]+"${CODE_FILES[@]}"}")"
+# only treat as a retry loop if a retry/except keyword is nearby in the file
+retry_loops=""
+if [[ -n "$LOOP_HITS" ]]; then
+  while IFS= read -r line; do
+    file="${line%%:*}"
+    if grep -qiE '(retry|num_retries|except|completion\(|create\()' "$file" 2>/dev/null; then
+      retry_loops+="$line"$'\n'
+    fi
+  done <<< "$LOOP_HITS"
+fi
+if [[ -n "${retry_loops//[$'\n']/}" ]]; then
+  fail "retries bounded (unbounded 'while True' retry loop)"
+  printf '%s' "$retry_loops" | sed '/^$/d;s/^/      /'
+else
+  pass "retries bounded"
+fi
+
+# --- Check 4: a fallback is configured when a router/model_list exists -----
+HAS_ROUTER="$(grep_files '(Router\(|model_list|model_name)' "${ALL_FILES[@]}")"
+if [[ -z "$HAS_ROUTER" ]]; then
+  skip "fallback configured (no router/model_list present)"
+else
+  HAS_FALLBACK="$(grep_files '(fallbacks|content_policy_fallbacks|context_window_fallbacks|default_fallbacks)' "${ALL_FILES[@]}")"
+  if [[ -n "$HAS_FALLBACK" ]]; then
+    pass "fallback configured"
+  else
+    fail "fallback configured (router/model_list present but no fallback list)"
+  fi
+fi
+
+# --- Check 5: config files parse and list >=2 model entries ----------------
+check_config_models() { # $1 = file
+  local f="$1" count=""
+  case "$f" in
+    *.json)
+      if command -v python3 >/dev/null 2>&1; then
+        count="$(python3 - "$f" <<'PY' 2>/dev/null
+import json,sys,re
+d=open(sys.argv[1]).read()
+try: obj=json.loads(d)
+except Exception: print("PARSEFAIL"); sys.exit(0)
+s=json.dumps(obj)
+print(len(re.findall(r'"model_name"|"model"\s*:', s)))
+PY
+)"
+      fi ;;
+    *.yaml|*.yml)
+      if command -v python3 >/dev/null 2>&1 && python3 -c 'import yaml' 2>/dev/null; then
+        count="$(python3 - "$f" <<'PY' 2>/dev/null
+import yaml,sys,re
+try: obj=yaml.safe_load(open(sys.argv[1]).read())
+except Exception: print("PARSEFAIL"); sys.exit(0)
+print(len(re.findall(r'model_name|(^|\s)model\s*:', str(obj))))
+PY
+)"
+      else
+        # no yaml lib: fall back to counting model_name occurrences textually
+        count="$(grep -cE 'model_name' "$f" 2>/dev/null || echo 0)"
+      fi ;;
+  esac
+  echo "${count:-}"
+}
+
+CONFIG_FILES=("${YAML_FILES[@]+"${YAML_FILES[@]}"}" "${JSON_FILES[@]+"${JSON_FILES[@]}"}")
+relevant_config=0
+for f in "${CONFIG_FILES[@]+"${CONFIG_FILES[@]}"}"; do
+  [[ -z "$f" ]] && continue
+  if grep -qE '(model_list|model_name|litellm|router_settings)' "$f" 2>/dev/null; then
+    relevant_config=1
+    res="$(check_config_models "$f")"
+    if [[ "$res" == "PARSEFAIL" ]]; then
+      fail "config parses ($f does not parse)"
+    elif [[ "$res" =~ ^[0-9]+$ ]] && [[ "$res" -ge 2 ]]; then
+      pass "config parses with >=2 model entries ($f)"
+    else
+      fail "config has >=2 model entries ($f has ${res:-0}; need a fallback target)"
+    fi
+  fi
+done
+[[ $relevant_config -eq 0 ]] && skip "config parses with >=2 models (no router config file present)"
+
+echo "---"
+if [[ $fail_count -eq 0 ]]; then
+  echo "verify.sh: all applicable checks passed."
+  exit 0
+else
+  echo "verify.sh: $fail_count check(s) FAILED."
+  exit 1
+fi

package/skills/logistics-ops/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: logistics-ops
+description: "Use when an order is paid and packed and the box now has to physically move, go sideways, or come home — pick a carrier/service and cut a label, react to a tracker that fired a delivery exception, get ahead of 'where is my order' tickets, run a return/exchange/refund decision and the reverse label, file a carrier claim before the window closes, or set return-window / restocking-fee policy. Triggers: 'which carrier and service for order #1043, cut me the label', 'the tracker says delivery exception — what do I tell the customer', 'customers keep opening where-is-my-order tickets', 'a package arrived smashed, how long to file a FedEx claim', 'gestiona la devolución de este pedido, quiere cambiar la talla', 'quin transportista surt més barat per a aquest enviament'. NOT setting stock levels or reorder points (that is inventory), NOT sourcing or buying from suppliers (that is procurement), NOT writing the on-voice apology to the customer (that is customer-support)."
+tags: [logistics, shipping, carriers, returns, reverse-logistics, fulfillment, tracking]
+recommends: [inventory, procurement, customer-support, api-connector-builder, webhooks, bookkeeping]
+origin: risco
+---
+
+# Logistics-ops — the box is packed, now move it, watch it, and bring it home cheap
+
+You run the parcel as an operation. An order is **paid and packed**; from here the
+box has exactly four things it can do — ship out, travel, go sideways, or come
+back — and your job is to make each one cost the least while keeping the promise the
+order made. You ship on the cheapest service that still hits the delivery date, you
+catch the parcel when it goes wrong *before the customer notices*, and you turn the
+return into the smallest possible revenue loss.
+
+You do **not** decide what stock to hold or when to reorder — that is
+[`inventory`](../inventory/SKILL.md). You do not source or buy from suppliers —
+that is [`procurement`](../procurement/SKILL.md) (inbound from vendors, not outbound
+to customers). You do not write the on-voice customer reply — you hand the *facts and
+the trigger* to [`customer-support`](../customer-support/SKILL.md) and it writes the
+apology around them. You do not host the carrier-API webhook listener — that is
+[`api-connector-builder`](../api-connector-builder/SKILL.md) /
+[`webhooks`](../webhooks/SKILL.md). And you do not post the refund to the books —
+that is [`bookkeeping`](../bookkeeping/SKILL.md). You decide *what calls to make and
+when*, and *what to do with the box*.
+
+## The parcel lifecycle — the spine
+
+Every parcel moves through four legs. Two of them (EXCEPT, REVERSE) are where
+operators lose money by treating them as edge cases. They are not: exceptions hit
+**8-12% of parcels** (≈18% at peak) and returns run **≈20% of online sales**. Build
+both as first-class paths.
+
+```text
+  SHIP            TRACK             EXCEPT             REVERSE
+  rate-shop  ──►  watch the    ──►  tiered        ──►  return / exchange /
+  + cut label     tracker           response           refund + reverse label
+  + validate      (event-driven)    by severity        + carrier claim
+  address                              ▲                   ▲
+                       └── exception ──┘                   │
+                       └────────── return requested ───────┘
+```
+
+- **SHIP** — order is paid and packed; choose carrier + service against the delivery
+  promise, validate the address, buy the label.
+- **TRACK** — label exists; watch the tracker for status changes via webhook, not
+  polling, and notify the customer proactively.
+- **EXCEPT** — the tracker fired a delivery exception; classify it and respond on a
+  severity clock.
+- **REVERSE** — the customer wants it back / it came back damaged; run the
+  disposition decision, cut the reverse label, file any claim.
+
+## Ship — rate-shop, don't reflex
+
+Pick the service against **the delivery promise the order actually made**, not your
+habit. "2-day paid at checkout" sets the constraint; the cheapest service that still
+delivers by that date wins. Shipping everything one way leaves money on the table on
+every order.
+
+**Audit the surcharges — the headline is a lie.** The 2026 carrier increase reads as
+**5.9%** (UPS GRI effective 2025-12-22, FedEx 5.9% effective 2026-01-05) but lands at
+a real **8-12%** once new dimensional/cubic criteria for Additional Handling and
+Large Package kick in; USPS Ground Advantage is up **7.8%**, and the residential
+surcharge climbed ~8% into the mid-$6 range. So compare *landed* cost per shipment
+including DIM weight and surcharges, never the base rate card.
+
+**Validate the address before you buy the label.** A bad/undeliverable address is the
+cheapest exception to prevent and the most common one to suffer — fix it at the API,
+not after a failed attempt.
+
+```python
+# EasyPost: build the shipment, rate-shop, buy the cheapest that fits the promise.
+shipment = client.shipment.create(
+    to_address=to_addr,        # validated upstream
+    from_address=from_addr,
+    parcel={"length": 9, "width": 6, "height": 3, "weight": 12},  # drives DIM
+)
+# Filter to services that hit the promised delivery date, THEN take the cheapest.
+rate = shipment.lowest_rate(carriers=["USPS", "UPS", "FedEx"])
+bought = client.shipment.buy(shipment.id, rate=rate)
+# `bought.tracker` is now live (pre_transit → ... → delivered).
+```
+
+```text
+Bad : "We always ship UPS Ground." → overpays on light zone-1 parcels,
+      misses the 2-day promise, eats the surcharge increase blind.
+Good: rate-shop USPS/UPS/FedEx against the 2-day promise, compare landed
+      cost incl. DIM + surcharges, buy the cheapest service that still hits
+      the date. Validate the address first.
+```
+
+## Track — kill WISMO before it becomes a ticket
+
+WISMO ("where is my order") is **30-40% of ecommerce support contacts** (50%+ at peak)
+and each human-handled ticket costs **$5-$22**. The whole game is to message the
+customer *before* they message you.
+
+**Use the tracker webhook, not a polling loop.** EasyPost pushes `tracker.updated`
+events as the parcel moves; subscribe and react to status changes — `in_transit`,
+`out_for_delivery`, `exception`, `delivered`. Polling burns API calls and lags reality.
+(The listener *hosting* is [`webhooks`](../webhooks/SKILL.md)' job; you decide which
+events fire which message.)
+
+**The window is tiny.** The difference between a handled exception and a WISMO ticket
+is often only **4-12 hours** of response time. Fire a proactive notification on the
+status change and the ticket never gets created — and 98% of consumers say shipping
+shapes brand loyalty, so this *is* retention work.
+
+You supply the trigger and the fact ("FedEx shows out-for-delivery, EDD today").
+[`customer-support`](../customer-support/SKILL.md) writes the tone and owns the SLA on
+the reply. Never let support invent an ETA the carrier hasn't given.
+
+## Except — the tiered exception protocol
+
+A failed delivery costs **~$20-30 direct and $140+ in lost future revenue**, so triage
+by severity, don't treat every exception the same. First **normalize** the code:
+carriers label the same event differently (FedEx, UPS, USPS each use distinct
+exception codes for address / weather / damage / failed-attempt — see the reference
+glossary), so map to a bucket before you route.
+
+| Exception type        | Act on the parcel                              | Customer-comms SLA            |
+| --------------------- | ---------------------------------------------- | ----------------------------- |
+| Damage / past EDD     | Open claim path, prep replacement/refund       | Proactive outreach **same business day** |
+| Address / access      | Correct address, intercept, break reattempt    | Resolve within **24 h**       |
+| Weather / operational | Hold, let carrier recover, monitor             | **48-h** check-in cadence     |
+| Failed attempt        | Reattempt or redirect to pickup before cycle 2 | Within **24 h**               |
+
+Sequence is always **act → notify → escalate**: fix the parcel first (intercept,
+reattempt, claim), *then* send the proactive message, *then* escalate to the carrier
+if the clock runs out. Don't notify before you have an action, and don't escalate
+before you've notified.
+
+## Claims — file before the window closes
+
+Claim windows are hard deadlines. Miss them and the money is simply gone. Capture
+evidence **at exception detection**, because you cannot reconstruct it later.
+
+| Carrier | Damaged / missing contents      | Lost / undelivered           | Guaranteed-service refund |
+| ------- | ------------------------------- | ---------------------------- | ------------------------- |
+| USPS    | ≤ **60 days** from mailing*     | (varies by service)          | —                         |
+| UPS     | notice ≤ **60 days** of delivery| ≤ 60 days of scheduled deliv.| ≤ **15 days** of invoice  |
+| FedEx   | ≤ **60 days** of ship date (intl **21 d**) | up to **9 months** | ≤ **15 days** of invoice  |
+
+\*Windows vary by service class; confirm against the full matrix in references before
+relying on a date.
+
+Evidence checklist — gather **now**, at detection:
+
+- [ ] Tracking number + the exception event/screenshot (timestamped)
+- [ ] Photos of the damaged item *and* the packaging
+- [ ] Declared/invoice value and the original label
+- [ ] Weight and dimensions as shipped
+- [ ] For guaranteed-service refunds: the carrier invoice (15-day clock starts there)
+
+## Reverse — turn the return into the smallest loss
+
+Returns are **≈20% of online sales** (NRF: 19.3% returned in 2025; apparel runs
+20-40%), not an edge case — design the reverse flow as a primary path. Route by
+*reason*, and default to retaining revenue before handing back cash.
+
+| Return reason       | Default disposition                          | Why                                   |
+| ------------------- | -------------------------------------------- | ------------------------------------- |
+| Defective / damaged | Refund or replacement, **no restocking fee** | Your fault — fee kills the relationship |
+| Wrong item sent     | Replacement + free reverse label             | Your fault — fix fast                  |
+| Changed mind / size | **Instant exchange** or store credit first   | Retains the revenue, often cheaper than reverse freight |
+| Not as described    | Refund or store credit                       | Listing risk — fix the listing too    |
+| Low-value bulky     | **Keep-it / refund** (no return)             | Reverse freight > item value          |
+
+**Tune the policy as both a conversion lever and a cost lever.** 82% of consumers rank
+free returns as a key purchase factor and 81% read the policy before buying — but 72%
+of merchants now charge a restocking fee, typically **10-25%** (15-25% standard), with
+windows of **30-90 days**. Charge the fee only where the reason is buyer-side
+("changed mind"), never on a defect. And screen for fraud: ~9% of returns are
+fraudulent and 85% of retailers now use AI to flag them — flag mismatched
+weight/serial, serial returners, and wardrobing.
+
+```python
+# The reverse label is the SAME create call with is_return: true (swaps to/from).
+return_shipment = client.shipment.create(
+    to_address=from_addr,      # back to your warehouse
+    from_address=to_addr,      # from the customer
+    parcel=parcel,
+    is_return=True,
+)
+return_label = client.shipment.buy(
+    return_shipment.id, rate=return_shipment.lowest_rate()
+)
+```
+
+Hand the **restock quantity** to [`inventory`](../inventory/SKILL.md) (does it go back
+to sellable stock?) and the **refund accounting** to
+[`bookkeeping`](../bookkeeping/SKILL.md) (the credit-note entry). You decide the
+disposition; they record the consequence.
+
+## Anti-patterns
+
+| Anti-pattern | Why it costs you | Do instead |
+| ------------ | ---------------- | ---------- |
+| Ship by habit, one carrier always | Overpays per order, misses promises | Rate-shop the three against the promise |
+| Trust the "5.9%" headline | Real increase is 8-12% with DIM/surcharges | Audit landed cost per shipment |
+| Poll the tracker on a timer | Lags reality, burns API calls | Subscribe to `tracker.updated` webhooks |
+| Wait for the WISMO ticket | Ticket costs $5-22; you missed the 4-12 h window | Notify proactively on status change |
+| Same urgency for damage and weather | Wastes effort or misses the costly one | Tier by severity (table above) |
+| Cash-refund by default | Hands back revenue you could keep | Offer exchange / store-credit first |
+| No return-window or restocking policy | Can't defend the cost or the conversion | Set 30-90 d window, 10-25% fee buyer-side only |
+| Restocking fee on a defect | Burns the relationship on your own fault | Free reverse label for defective/wrong-item |
+| Capture claim evidence "later" | Window closes, money gone; can't reconstruct | Photograph + record value/weight at detection |
+| Let support invent the ETA | A wrong promise becomes a second complaint | Give support the tracker fact, not a guess |
+| Treat returns as an edge case | They're ~20% of orders | Design REVERSE as a primary path |
+
+## References
+
+Full per-carrier exception-code glossary (FedEx/UPS/USPS → the four buckets), the
+complete claim-window matrix with required evidence per claim type, and runnable
+EasyPost snippets (rate-shop + one-call buy, tracker webhook handler shape, the
+`is_return: true` reverse label) live in
+[`references/carriers-and-claims.md`](references/carriers-and-claims.md).

package/skills/logistics-ops/evals/README.md

@@ -0,0 +1,20 @@
+# Evals — logistics-ops
+
+`cases.yaml` holds three groups: `should_trigger`, `should_not_trigger`, and a
+`capability` case. These are LLM-graded routing and capability checks, not unit
+tests — there is no `verify.sh`, because the skill emits operational judgment (a
+carrier choice, an exception-response plan, a return disposition, a claim-filing
+call), not a single machine-checkable artifact. Run them through whatever eval
+harness the repo provides, or by hand: feed each `should_trigger` prompt to the
+router and confirm it selects `logistics-ops` — including the non-obvious one (the
+"delivery exception, what do I tell the customer" prompt that never says "shipping")
+and the Spanish/Catalan return and rate-shop phrasings. Feed each
+`should_not_trigger` prompt and confirm it routes to the named sibling
+(`inventory`, `procurement`, `customer-support`, `bookkeeping`, `webhooks`) and not
+here; every `route_to` id must resolve to a real sibling skill. Grade the
+`capability` case against its `must_include` rubric on an actual generated answer:
+tick each line — damage → same-business-day outreach, the claim window + evidence at
+detection, the dual 60-day/15-day clocks, the proactive tracker-fact message with
+tone handed to customer-support, exchange/store-credit before cash with no
+restocking fee on a defect, and the hand-offs to bookkeeping and inventory — and
+confirm it never invents an ETA the carrier didn't give.