Logistics Exception Management

Logistics Exception Management

Overview

This public intake copy packages plugins/antigravity-awesome-skills-claude/skills/logistics-exception-management from https://github.com/sickn33/antigravity-awesome-skills into the native Omni Skills editorial shape without hiding its origin.

Use it when the operator needs the upstream workflow, support files, and repository context to stay intact while the public validator and private enhancer continue their normal downstream flow.

This intake keeps the copied upstream files intact and uses the external_source block in metadata.json plus ORIGIN.md as the provenance anchor for review.

Imported source sections that did not map cleanly to the public headings are still preserved below or in the support files. Notable imported sections: Role and Context, Core Knowledge, Decision Frameworks, Key Edge Cases, Communication Patterns, Escalation Protocols.

When to Use This Skill

Use this section as the trigger filter. It should make the activation boundary explicit before the operator loads files, runs commands, or opens a pull request.

• Use this skill when dealing with deviations from planned logistics operations, such as transit delays, damaged shipments, lost cargo, or when initiating and managing claims and disputes with freight carriers.

• Logistics Exception Management

• Use when provenance needs to stay visible in the answer, PR, or review packet.
• Use when copied upstream references, examples, or scripts materially improve the answer.
• Use when the workflow should remain reviewable in the public intake repo before the private enhancer takes over.

Operating Table

Workflow

This workflow is intentionally editorial and operational at the same time. It keeps the imported source useful to the operator while still satisfying the public intake standards that feed the downstream enhancer flow.

1. Confirm the user goal, the scope of the imported workflow, and whether this skill is still the right router for the task.
2. Read the overview and provenance files before loading any copied upstream support files.
3. Load only the references, examples, prompts, or scripts that materially change the outcome for the current request.
4. Execute the upstream workflow while keeping provenance and source boundaries explicit in the working notes.
5. Validate the result against the upstream expectations and the evidence you can point to in the copied files.
6. Escalate or hand off to a related skill when the work moves out of this imported workflow's center of gravity.
7. Before merge or closure, record what was used, what changed, and what the reviewer still needs to verify.

Imported Workflow Notes

Imported: Role and Context

You are a senior freight exceptions analyst with 15+ years managing shipment exceptions across all modes — LTL, FTL, parcel, intermodal, ocean, and air. You sit at the intersection of shippers, carriers, consignees, insurance providers, and internal stakeholders. Your systems include TMS (transportation management), WMS (warehouse management), carrier portals, claims management platforms, and ERP order management. Your job is to resolve exceptions quickly while protecting financial interests, preserving carrier relationships, and maintaining customer satisfaction.

Examples

Example 1: Ask for the upstream workflow directly

Use @logistics-exception-management to handle <task>. Start from the copied upstream workflow, load only the files that change the outcome, and keep provenance visible in the answer.

Explanation: This is the safest starting point when the operator needs the imported workflow, but not the entire repository.

Example 2: Ask for a provenance-grounded review

Review @logistics-exception-management against metadata.json and ORIGIN.md, then explain which copied upstream files you would load first and why.

Explanation: Use this before review or troubleshooting when you need a precise, auditable explanation of origin and file selection.

Example 3: Narrow the copied support files before execution

Use @logistics-exception-management for <task>. Load only the copied references, examples, or scripts that change the outcome, and name the files explicitly before proceeding.

Explanation: This keeps the skill aligned with progressive disclosure instead of loading the whole copied package by default.

Example 4: Build a reviewer packet

Review @logistics-exception-management using the copied upstream files plus provenance, then summarize any gaps before merge.

Explanation: This is useful when the PR is waiting for human review and you want a repeatable audit packet.

Best Practices

Treat the generated public skill as a reviewable packaging layer around the upstream repository. The goal is to keep provenance explicit and load only the copied source material that materially improves execution.

• Keep the imported skill grounded in the upstream repository; do not invent steps that the source material cannot support.
• Prefer the smallest useful set of support files so the workflow stays auditable and fast to review.
• Keep provenance, source commit, and imported file paths visible in notes and PR descriptions.
• Point directly at the copied upstream files that justify the workflow instead of relying on generic review boilerplate.
• Treat generated examples as scaffolding; adapt them to the concrete task before execution.
• Route to a stronger native skill when architecture, debugging, design, or security concerns become dominant.

Troubleshooting

Problem: The operator skipped the imported context and answered too generically

Symptoms: The result ignores the upstream workflow in plugins/antigravity-awesome-skills-claude/skills/logistics-exception-management, fails to mention provenance, or does not use any copied source files at all. Solution: Re-open metadata.json, ORIGIN.md, and the most relevant copied upstream files. Check the external_source block first, then restate the provenance before continuing.

Problem: The imported workflow feels incomplete during review

Symptoms: Reviewers can see the generated SKILL.md, but they cannot quickly tell which references, examples, or scripts matter for the current task. Solution: Point at the exact copied references, examples, scripts, or assets that justify the path you took. If the gap is still real, record it in the PR instead of hiding it.

Problem: The task drifted into a different specialization

Symptoms: The imported skill starts in the right place, but the work turns into debugging, architecture, design, security, or release orchestration that a native skill handles better. Solution: Use the related skills section to hand off deliberately. Keep the imported provenance visible so the next skill inherits the right context instead of starting blind.

Related Skills

• @20-andruia-niche-intelligence - Use when the work is better handled by that native specialization after this imported skill establishes context.
• @advogado-criminal - Use when the work is better handled by that native specialization after this imported skill establishes context.
• @advogado-especialista - Use when the work is better handled by that native specialization after this imported skill establishes context.
• @agent-memory-systems - Use when the work is better handled by that native specialization after this imported skill establishes context.

Additional Resources

Use this support matrix and the linked files below as the operator packet for this imported skill. They should reflect real copied source material, not generic scaffolding.

• communication-templates.md
• decision-frameworks.md
• edge-cases.md
• communication-templates.md
• decision-frameworks.md
• edge-cases.md

Imported Reference Notes

Imported: Additional Resources

• For detailed decision frameworks, escalation matrices, and mode-specific workflows, see decision-frameworks.md
• For the comprehensive edge case library with full analysis, see edge-cases.md
• For complete communication templates with variables and tone guidance, see communication-templates.md

When to Use

Use this skill when you need to triage and resolve logistics exceptions or design exception-handling playbooks:

• Handling delays, damages, shortages, misdeliveries, and claims across LTL, FTL, parcel, intermodal, ocean, or air.
• Defining escalation rules, severity classification, and “eat‑the‑cost vs fight‑the‑claim” thresholds for your network.
• Building SOPs, dashboards, or automation for OS&D, claims workflows, and customer communications during freight disruptions.

Imported: Core Knowledge

Exception Taxonomy

Every exception falls into a classification that determines the resolution workflow, documentation requirements, and urgency:

• Delay (transit): Shipment not delivered by promised date. Subtypes: weather, mechanical, capacity (no driver), customs hold, consignee reschedule. Most common exception type (~40% of all exceptions). Resolution hinges on whether delay is carrier-fault or force majeure.
• Damage (visible): Noted on POD at delivery. Carrier liability is strong when consignee documents on the delivery receipt. Photograph immediately. Never accept "driver left before we could inspect."
• Damage (concealed): Discovered after delivery, not noted on POD. Must file concealed damage claim within 5 days of delivery (industry standard, not law). Burden of proof shifts to shipper. Carrier will challenge — you need packaging integrity evidence.
• Damage (temperature): Reefer/temperature-controlled failure. Requires continuous temp recorder data (Sensitech, Emerson). Pre-trip inspection records are critical. Carriers will claim "product was loaded warm."
• Shortage: Piece count discrepancy at delivery. Count at the tailgate — never sign clean BOL if count is off. Distinguish driver count vs warehouse count conflicts. OS&D (Over, Short & Damage) report required.
• Overage: More product delivered than on BOL. Often indicates cross-shipment from another consignee. Trace the extra freight — somebody is short.
• Refused delivery: Consignee rejects. Reasons: damaged, late (perishable window), incorrect product, no PO match, dock scheduling conflict. Carrier is entitled to storage charges and return freight if refusal is not carrier-fault.
• Misdelivered: Delivered to wrong address or wrong consignee. Full carrier liability. Time-critical to recover — product deteriorates or gets consumed.
• Lost (full shipment): No delivery, no scan activity. Trigger trace at 24 hours past ETA for FTL, 48 hours for LTL. File formal tracer with carrier OS&D department.
• Lost (partial): Some items missing from shipment. Often happens at LTL terminals during cross-dock handling. Serial number tracking critical for high-value.
• Contaminated: Product exposed to chemicals, odors, or incompatible freight (common in LTL). Regulatory implications for food and pharma.

Carrier Behaviour by Mode

Understanding how different carrier types operate changes your resolution strategy:

• LTL carriers (FedEx Freight, XPO, Estes): Shipments touch 2-4 terminals. Each touch = damage risk. Claims departments are large and process-driven. Expect 30-60 day claim resolution. Terminal managers have authority up to ~$2,500.
• FTL/truckload (asset carriers + brokers): Single-driver, dock-to-dock. Damage is usually loading/unloading. Brokers add a layer — the broker's carrier may go dark. Always get the actual carrier's MC number.
• Parcel (UPS, FedEx, USPS): Automated claims portals. Strict documentation requirements. Declared value matters — default liability is very low ($100 for UPS). Must purchase additional coverage at shipping.
• Intermodal (rail + drayage): Multiple handoffs. Damage often occurs during rail transit (impact events) or chassis swap. Bill of lading chain determines liability allocation between rail and dray.
• Ocean (container shipping): Governed by Hague-Visby or COGSA (US). Carrier liability is per-package ($500 per package under COGSA unless declared). Container seal integrity is everything. Surveyor inspection at destination port.
• Air freight: Governed by Montreal Convention. Strict 14-day notice for damage, 21 days for delay. Weight-based liability limits unless value declared. Fastest claims resolution of all modes.

Claims Process Fundamentals

• Carmack Amendment (US domestic surface): Carrier is liable for actual loss or damage with limited exceptions (act of God, act of public enemy, act of shipper, public authority, inherent vice). Shipper must prove: goods were in good condition when tendered, goods arrived damaged/short, and the amount of damages.
• Filing deadline: 9 months from delivery date for US domestic (49 USC § 14706). Miss this and the claim is time-barred regardless of merit.
• Documentation required: Original BOL (showing clean tender), delivery receipt (showing exception), commercial invoice (proving value), inspection report, photographs, repair estimates or replacement quotes, packaging specifications.
• Carrier response: Carrier has 30 days to acknowledge, 120 days to pay or decline. If they decline, you have 2 years from the decline date to file suit.

Seasonal and Cyclical Patterns

• Peak season (Oct-Jan): Exception rates increase 30-50%. Carrier networks are strained. Transit times extend. Claims departments slow down. Build buffer into commitments.
• Produce season (Apr-Sep): Temperature exceptions spike. Reefer availability tightens. Pre-cooling compliance becomes critical.
• Hurricane season (Jun-Nov): Gulf and East Coast disruptions. Force majeure claims increase. Rerouting decisions needed within 4-6 hours of storm track updates.
• Month/quarter end: Shippers rush volume. Carrier tender rejections spike. Double-brokering increases. Quality suffers across the board.
• Driver shortage cycles: Worst in Q4 and after new regulation implementation (ELD mandate, FMCSA drug clearinghouse). Spot rates spike, service drops.

Fraud and Red Flags

• Staged damages: Damage patterns inconsistent with transit mode. Multiple claims from same consignee location.
• Address manipulation: Redirect requests post-pickup to different addresses. Common in high-value electronics.
• Systematic shortages: Consistent 1-2 unit shortages across multiple shipments — indicates pilferage at a terminal or during transit.
• Double-brokering indicators: Carrier on BOL doesn't match truck that shows up. Driver can't name their dispatcher. Insurance certificate is from a different entity.

Imported: Decision Frameworks

Severity Classification

Assess every exception on three axes and take the highest severity:

Financial Impact:

• Level 1 (Low): < $1,000 product value, no expedite needed
• Level 2 (Moderate): $1,000 - $5,000 or minor expedite costs
• Level 3 (Significant): $5,000 - $25,000 or customer penalty risk
• Level 4 (Major): $25,000 - $100,000 or contract compliance risk
• Level 5 (Critical): > $100,000 or regulatory/safety implications

Customer Impact:

• Standard customer, no SLA at risk → does not elevate
• Key account with SLA at risk → elevate by 1 level
• Enterprise customer with penalty clauses → elevate by 2 levels
• Customer's production line or retail launch at risk → automatic Level 4+

Time Sensitivity:

• Standard transit with buffer → does not elevate
• Delivery needed within 48 hours, no alternative sourced → elevate by 1
• Same-day or next-day critical (production shutdown, event deadline) → automatic Level 4+

Eat-the-Cost vs Fight-the-Claim

This is the most common judgment call. Thresholds:

• < $500 and carrier relationship is strong: Absorb. The admin cost of claims processing ($150-250 internal) makes it negative-ROI. Log for carrier scorecard.
• $500 - $2,500: File claim but don't escalate aggressively. This is the "standard process" zone. Accept partial settlements above 70% of value.
• $2,500 - $10,000: Full claims process. Escalate at 30-day mark if no resolution. Involve carrier account manager. Reject settlements below 80%.
• > $10,000: VP-level awareness. Dedicated claims handler. Independent inspection if damage. Reject settlements below 90%. Legal review if denied.
• Any amount + pattern: If this is the 3rd+ exception from the same carrier in 30 days, treat it as a carrier performance issue regardless of individual dollar amounts.

Priority Sequencing

When multiple exceptions are active simultaneously (common during peak season or weather events), prioritize:

1. Safety/regulatory (temperature-controlled pharma, hazmat) — always first
2. Customer production shutdown risk — financial multiplier is 10-50x product value
3. Perishable with remaining shelf life < 48 hours
4. Highest financial impact adjusted for customer tier
5. Oldest unresolved exception (prevent aging beyond SLA)

Imported: Key Edge Cases

These are situations where the obvious approach is wrong. Brief summaries here — see edge-cases.md for full analysis.

1. Pharma reefer failure with disputed temps: Carrier shows correct set-point; your Sensitech data shows excursion. The dispute is about sensor placement and pre-cooling. Never accept carrier's single-point reading — demand continuous data logger download.

2. Consignee claims damage but caused it during unloading: POD is signed clean, but consignee calls 2 hours later claiming damage. If your driver witnessed their forklift drop the pallet, the driver's contemporaneous notes are your best defense. Without that, concealed damage claim against you is likely.

3. 72-hour scan gap on high-value shipment: No tracking updates doesn't always mean lost. LTL scan gaps happen at busy terminals. Before triggering a loss protocol, call the origin and destination terminals directly. Ask for physical trailer/bay location.

4. Cross-border customs hold: When a shipment is held at customs, determine quickly if the hold is for documentation (fixable) or compliance (potentially unfixable). Carrier documentation errors (wrong harmonized codes on the carrier's portion) vs shipper errors (incorrect commercial invoice values) require different resolution paths.

5. Partial deliveries against single BOL: Multiple delivery attempts where quantities don't match. Maintain a running tally. Don't file shortage claim until all partials are reconciled — carriers will use premature claims as evidence of shipper error.

6. Broker insolvency mid-shipment: Your freight is on a truck, the broker who arranged it goes bankrupt. The actual carrier has a lien right. Determine quickly: is the carrier paid? If not, negotiate directly with the carrier for release.

7. Concealed damage discovered at final customer: You delivered to distributor, distributor delivered to end customer, end customer finds damage. The chain-of-custody documentation determines who bears the loss.

8. Peak surcharge dispute during weather event: Carrier applies emergency surcharge retroactively. Contract may or may not allow this — check force majeure and fuel surcharge clauses specifically.

Imported: Communication Patterns

Tone Calibration

Match communication tone to situation severity and relationship:

• Routine exception, good carrier relationship: Collaborative. "We've got a delay on PRO# X — can you get me an updated ETA? Customer is asking."
• Significant exception, neutral relationship: Professional and documented. State facts, reference BOL/PRO, specify what you need and by when.
• Major exception or pattern, strained relationship: Formal. CC management. Reference contract terms. Set response deadlines. "Per Section 4.2 of our transportation agreement dated..."
• Customer-facing (delay): Proactive, honest, solution-oriented. Never blame the carrier by name. "Your shipment has experienced a transit delay. Here's what we're doing and your updated timeline."
• Customer-facing (damage/loss): Empathetic, action-oriented. Lead with the resolution, not the problem. "We've identified an issue with your shipment and have already initiated [replacement/credit]."

Key Templates

Brief templates below. Full versions with variables in communication-templates.md.

Initial carrier inquiry: Subject: Exception Notice — PRO# {pro} / BOL# {bol}. State: what happened, what you need (ETA update, inspection, OS&D report), and by when.

Customer proactive update: Lead with: what you know, what you're doing about it, what the customer's revised timeline is, and your direct contact for questions.

Escalation to carrier management: Subject: ESCALATION: Unresolved Exception — {shipment_ref} — {days} Days. Include timeline of previous communications, financial impact, and what resolution you expect.

Imported: Escalation Protocols

Automatic Escalation Triggers

Escalation Chain

Level 1 (Analyst) → Level 2 (Team Lead, 4 hours) → Level 3 (Manager, 24 hours) → Level 4 (Director, 48 hours) → Level 5 (VP, 72+ hours or any Level 5 severity)

Imported: Performance Indicators

Track these metrics weekly and trend monthly:

Imported: Limitations

• Use this skill only when the task clearly matches the scope described above.
• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.