logistics_exception_management v1.0.0

name: logistics_exception_management description: Triage and resolve freight and shipment exceptions (delays, damage, shortage, loss, refusals) across LTL, FTL, parcel, intermodal, ocean, and air: classifies the exception, assigns severity, applies mode-specific triage playbooks, computes claim-filing deadlines, and drafts carrier/broker/customer escalation messages and OS&D reports. Use when a shipment is late, damaged, short, lost, refused, misdelivered, hit with accessorials, or when a freight claim needs to be filed or negotiated.

Logistics Exception Management

Purpose

Turn a freight exception into a resolved outcome with the money protected: classify the problem, triage by severity and dollars, preserve evidence, hold carriers and brokers to written deadlines, and file defensible claims. Built for an agent that has to act in minutes, not a textbook.

Workflow

1. Classify

Map the report to one exception type: delay, visible damage, concealed damage, temperature excursion, shortage, overage, refusal, misdelivery, or accessorial/billing dispute. Confirm the mode (LTL, FTL, parcel, intermodal, ocean, air), the PRO/BOL/airbill number, and the ship date. Details for each type are in references/triage-playbook.md.

2. Triage severity (first 15 minutes)

Score on three axes:

• Financial exposure: declared or invoice value at risk, plus consequential cost (line-down, customer penalty, re-ship).
• Customer impact: missed commitment date, perishable window, end-customer already notified.
• Evidence fragility: is the freight still sealed (good), or has someone already broken it down, signed a clean BOL, or discarded packaging (bad, act now).

Severity sets the tempo: S1 = act in the hour, assign an owner, notify the customer proactively; S2 = act today; S3 = file and track.

3. Preserve evidence before touching anything else

Do not let receiving break down the load until the evidence is captured. Photograph wide shots, close-ups, labels, pallet condition, seal numbers. Note exceptions on the delivery receipt with specifics, never the word "damaged" alone. If concealed damage is found later, stop: keep cargo and original packaging exactly as found, then run the concealed-damage playbook in references/triage-playbook.md.

4. Compute deadlines

Run bin/claim_deadline.py with the delivery date and mode. It prints the filing and notice windows for the scenario (Carmack 9-month window, concealed-damage 5-day notice, ocean 3-day notice, Montreal Convention 14/21-day + 2-year windows). File a claim at the earliest deadline, never the latest; tariffs can tighten the legal floor.

5. Root-cause before blaming

Five-minute triage: was the carrier at fault, was the shipper at fault (packaging, loading, BOL errors), was it force majeure, or is the cause still unknown? Match against the carrier's likely Carmack defenses (act of God, public enemy, shipper act, public authority, inherent vice; the burden to prove one sits with the carrier). A delay with a clean POD points at scheduling or capacity, not damage; a shortage with a clean piece count at origin points at pilferage or cross-shipment.

6. Escalate on a tiered clock

• Carrier/broker: written notice, one owner, a response deadline proportional to severity. Escalate to management or legal when the dollar threshold or elapsed time crosses the lane's limit.
• Customer: proactive, honest, solution-first. Never blame the carrier by name to the customer. Lead with the remedy, not the problem. Use the message templates in assets/escalation-templates.md. Tone-calibrate per relationship (collaborative for a good carrier, formal with contract citations when the relationship is strained).

7. File the claim, negotiate, close the loop

File the claim package in writing: shipment ID, asserted liability, a specified or determinable dollar amount, BOL, POD with exceptions noted, photos, invoice, and (for temperature) recorder data. Track it, answer carrier information requests fast (silence gets the file closed), and close with the customer once money or replacement lands. Log the outcome and the root cause so the lane learns; see Operating Rules.

Output Contract

Every exception run produces:

• Classification: type, mode, severity (S1/S2/S3) with the three triage scores.
• Evidence checklist status: what was captured, what is missing, what is at risk.
• Deadline set: computed dates from bin/claim_deadline.py, plus which filing is due first.
• Action plan: owner, next step, response deadline, escalation tier.
• Messages drafted: carrier/broker notice and customer notice from the templates, filled in.
• Claim package: if filing, the five required elements (identity of shipment, asserted liability, amount, BOL, POD/photos).
• Close-out note: root cause, dollars recovered, lesson for the lane.

Operating Rules

1. Deadlines beat perfection. A thin claim filed on day 8 of a 9-month window loses; a complete one filed in week one wins. File early, supplement later.
2. Never sign a clean delivery receipt when the count or condition is off. A clean signature hands the carrier its best defense.
3. Concealed damage is a special case: five-day notice is an industry standard, not a law, and tariffs vary. Treat every concealed find as urgent and verify the tariff in play.
4. Delays are usually not compensable without a written guaranteed delivery commitment; the BOL only promises reasonable dispatch. Pursue delay claims for refunds, credits, or contract service credits rather than cargo-loss framing.
5. Carmack covers interstate motor freight. It does not cover ocean (COGSA/Hague-Visby family) or international air (Montreal Convention): use the right regime, never the wrong one.
6. Released value caps recovery. Check the BOL's declared/released value before promising a dollar figure.
7. Keep one owner per exception and write everything down. Five people sharing responsibility means nobody has it.
8. Every close-out feeds back: update the lane's failure log with root cause, carrier, and what the evidence gap was, so the next shipment prevents it.