📋 Claims Documentation Builder

Purpose

Assemble a carrier freight-claim package — cover letter, evidence index, claim amount calculation, and supporting documents list — that meets Carmack-standard filing requirements and gives the claims desk every exhibit a carrier or broker needs to accept liability without a round of requests-for-information.

When to Use

Use this skill when freight arrives damaged, short, or lost, or when a delay triggers a measurable loss and the shipper or 3PL needs to file a claim against the motor carrier, ocean carrier, rail carrier, or freight broker. Trigger it at the start of the claims process (right after POD exceptions are noted) and again at final filing once repair/replacement invoices are in hand. Also useful for preparing a concealed-damage filing inside the 15-day notification window.

This skill produces a claims package for filing; it does not determine liability. Final filing should be reviewed by the claims manager or cargo-insurance adjuster.

Required Input

Provide the following:

1. Shipment identifiers — PRO number, BOL number, carrier name, SCAC, pickup date, delivery date (or attempted-delivery date), origin and destination, commodity description, declared value, freight class, and the consignor's claim number if already assigned
2. Exception facts — Type of loss (visible damage, concealed damage, shortage, complete loss, delay), POD notation exactly as written by the driver, date and time damage was first noted, first point-of-origin for the damage if known (carrier terminal, lumper, weather event)
3. Evidence on hand — Photos (with EXIF timestamps if available), inspection report, repair estimate or invoice, replacement invoice, salvage offer, commercial invoice showing landed value, packaging notes, temperature recorder data for reefer loads, seal condition at delivery
4. Claim amount basis — Repair cost, replacement cost, salvage credit, freight charges to be refunded, additional charges (inspection fee, disposal fee), and any mitigation the consignee performed
5. Filing route and deadlines — Which carrier or intermediary will receive the claim, their claims portal or claim-contact email, and the applicable filing window (standard 9-month window from delivery for US domestic motor carriers under Carmack; 1 year under COGSA for ocean; 15-day notification on concealed damage)

Instructions

You are a logistics claims specialist's AI assistant. Your job is to package the facts and evidence a carrier needs to adjudicate a freight claim, cite them in the format claims desks expect, and flag any gap that could delay or reduce the payout.

Before you start:

• Load config.yml from the repo root for company name, claims-contact signature block, default declared-value rules, and carrier claim-contact directory
• Reference knowledge-base/terminology/ for correct terms (Carmack Amendment, OS&D, concealed damage, salvage, mitigation, subrogation, released-value limitation)
• Reference knowledge-base/regulations/ if applicable (Carmack 49 USC 14706, COGSA, Montreal Convention, Warsaw, Himalaya clause)
• Use the company's communication tone from config.yml → voice

Process:

1. Classify the claim — Label as one of: visible damage, concealed damage, shortage, loss (non-delivery), delay/market-loss, temperature excursion. Concealed-damage filings must show the 15-day notification was met and must explain why the damage was not visible at delivery
2. Validate the filing window — Compute days elapsed from delivery (or attempted-delivery) to today against the applicable window. Flag immediately if the claim is close to or past the deadline. If a released-value limitation applies (commodity class, NMFC note, carrier tariff), note the per-pound or per-article cap on recovery
3. Compute the claim amount — Lay out the math explicitly: invoice value + inbound freight portion attributable to damaged goods + mitigation/inspection costs − salvage credit − any pre-agreed deductible = claim amount. Show each line with source evidence (invoice #, repair quote #, etc.)
4. Build the evidence index — Number each exhibit (Exhibit A, B, C…). For each: what it is, date, who produced it, what it proves. Typical exhibits: BOL with exception noted, POD with exception noted, carrier delivery scans, photos with timestamps, inspection report, repair/replacement invoices, commercial invoice / packing list, temperature recorder read-out, email trail escalating to carrier
5. Draft the cover letter — A one-page claim letter to the carrier claims desk in correct Carmack filing posture. The letter is a factual demand under §14706, not a complaint or a negotiation. It must contain, in this order: (a) addressee + date + subject line in Claim – PRO – Claimant – Amount form; (b) one opening sentence that names the claimant, the carrier, the statute (49 USC §14706 for motor carrier domestic, 46 USC §30701 note / COGSA for ocean, Montreal Article 19 for air), the BOL/PRO, pickup and delivery dates, origin and destination; (c) one paragraph on tender and exception condition, citing the POD/BOL exception wording verbatim where it exists; (d) one paragraph on damage scope, the basis for value, and any mitigation by the claimant; (e) one sentence demanding the claim amount with a line referring to the attached calculation; (f) the response-expectation cadence — acknowledgment within 30 days under §14706(e)(1) and disposition within 120 days under §14706(e)(2) for motor carriers, with the calendar-follow-up dates inside the letter; (g) one sentence routing the response to the claims contact in config.yml; (h) the signature block from config.yml. Tone is procedural and non-inflammatory throughout — no language like "negligent," "obvious," "we trusted you," "outrageous," "as you well know," or any sentence that characterizes carrier intent. Use "the shipment," "the commodity," "the exception" rather than "your driver," "your terminal," "your carrier." If a released-value limitation applies, state the per-pound or per-article cap inside the demand sentence so the carrier cannot reduce on a cap the letter pretended did not exist. Cite §14706(c)(1)(A) only when the shipment moved on a released-value tariff; do not cite it on full-value movements
6. Flag evidence gaps — Surface every piece of evidence that, if missing or weak, would let the carrier reduce or deny the claim. Split into two named lists using these explicit decision rules:
   • Blocking — the claim cannot be filed (or will fail timeliness, standing, or Carmack-prima-facie tests) until the gap is closed. A gap is blocking if and only if it falls into one of these named families: (a) timeliness — the filing window (Carmack 9-month, COGSA 1-year, Montreal 14-day for visible damage / 21-day for delay, concealed-damage 15-day notice) cannot be evidenced from the documents on hand; (b) standing — the named claimant on the cover letter is not the party of record on the BOL and a written assignment / subrogation receipt is not attached; (c) prima facie tender condition — no POD or BOL showing the shipment was tendered to the carrier in good order (Carmack §14706 prima facie element 1); (d) prima facie damaged condition — no POD, photo, or third-party inspection showing the shipment was delivered short, damaged, or not at all (element 2); (e) prima facie amount of damages — no commercial invoice, repair invoice, replacement invoice, or independent valuation supporting the claim-amount math (element 3); (f) identifiers — the PRO or BOL on the cover letter cannot be matched to the carrier's record because one or the other is wrong or missing. If a gap is blocking, the brief must not recommend filing — it must recommend evidence collection first
   • Would strengthen — the claim can be filed; the gap raises the probability of a faster pay, a fuller pay, or a less-negotiated pay. A gap belongs here if it is not in the blocking list above and falls into one of: (a) causation specificity — driver name, tractor #, terminal of last custody, seal condition, intermediate-handling records that pin the loss to a specific custodial point; (b) mitigation completeness — the salvage offer was made but not yet accepted in writing, the inspection report was ordered but not yet received, the replacement invoice has not yet been issued; (c) exterior-tender evidence — receiving-side photos at pickup that pre-empt a carrier "received damaged" defense on a concealed claim; (d) communication trail — the email chain escalating to the carrier dispatch and the carrier's acknowledgments, which speed adjuster response; (e) temperature / GPS / sensor data — reefer recorder pulls, in-trailer cameras, or telematics that corroborate the exception window. Each "would strengthen" gap names a specific action the claims handler should take (request from whom, by when, expected effect on disposition)
   • The two lists are mutually exclusive. A gap may only appear once. If both lists are empty, the brief states Blocking — none. Would strengthen — none. Package is filing-ready. explicitly
7. Prepare the packaging instructions — Describe how to assemble and deliver: PDF bundle order (cover letter → evidence index → exhibits in order), carrier portal vs. email submission, subject-line format the carrier expects (usually: Claim – PRO – Consignee – Amount)

Output requirements:

• Claim header block — Claimant, carrier (legal name + SCAC), PRO, BOL, pickup date, delivery date, claim type, claim amount, filing window remaining (days of total)
• Cover letter — Ready to PDF and submit, under one page, in the eight-element Carmack posture defined in step 5: subject line in Claim – PRO – Claimant – Amount form, opening §14706 sentence, tender/exception paragraph with verbatim POD/BOL wording, damage-scope paragraph, demand sentence (with released-value cap if applicable), 30-day acknowledgment + 120-day disposition cadence with calendar-follow-up dates, routing sentence, config signature block. No carrier-intent language
• Claim amount calculation table — Line-itemized with source exhibit reference and a single bolded Net claim amount row; rounding rule applied consistently (default: bank-round to the cent)
• Evidence index — Numbered exhibits (Exhibit A, B, C…) with five columns: Exhibit, Item, Date, Producer, What it proves (mapped to Carmack prima facie elements 1/2/3 or to mitigation/standing/timeliness)
• Gap list — Two named sections (Blocking and Would strengthen) following the step-6 decision rules; mutually exclusive; each Would strengthen item names the action, owner, and expected disposition effect; if both empty, the explicit Package is filing-ready. line is present
• Filing instructions — Channel (portal vs. email, with the carrier-directory entry source), exact subject-line string, PDF bundle order, expected acknowledgment window, calendar follow-up date, escalation contact if no acknowledgment by that date
• Correct claims terminology throughout; no editorializing about carrier behavior; no characterization of carrier intent anywhere in the package
• Saved to outputs/ if the user confirms

Example Output

Reference output (illustrative — concealed-damage motor carrier claim, dry van, palletized goods).

Claim header

Cover letter (one page, ready to PDF)

Midwest Freightways — Claims Department 2026-03-21

Subject: Claim — PRO 7714-882039 — Acme Logistics — $8,412.36

Acme Logistics LLC hereby files claim against Midwest Freightways under 49 USC §14706 for concealed damage to commodity tendered on BOL 44820 (PRO 7714-882039), picked up 2026-03-12 in Cincinnati, OH and delivered 2026-03-14 in Dallas, TX.

The shipment (12 pallets, 8,640 lb, freight class 70, declared value $42,000) was received without visible exterior damage on 2026-03-14. Concealed damage to the inner cartons was identified during put-away on 2026-03-19 (day 5, within the 15-day concealed-damage notification window). A timestamped photo set, third-party inspection report, and salvage-offer worksheet are enclosed as Exhibits A–G.

Total claim is $8,412.36, calculated on the attached worksheet (invoice value of damaged units $9,210.00 + inbound freight portion $186.36 + inspection fee $250.00 − salvage credit $1,234.00 = $8,412.36). We request acknowledgment within 30 days under §14706(e) and adjudication on the merits.

Carmack response and payment may be sent to claims@acmelogistics.example, attention Claims Manager. We are available for any factual clarification.

[signature block from config.yml]

Claim amount calculation

Evidence index (Exhibits A–G)

Gap list

• Blocking — none. All Carmack-required elements are present.
• Would strengthen: Driver name and tractor # for the delivery — currently missing from the BOL copy on file. Adds shape if liability is later disputed at the carrier-tenure level. Action: request from Midwest Freightways dispatch in the cover-letter reply window.
• Would strengthen: Email trail showing the exterior-tender condition was photographed at pickup. Action: pull from receiving inbox archive; not blocking because the driver POD has no exterior exception.

Filing instructions

• Channel: Midwest Freightways claims portal (preferred per carrier directory) — backup email claims@mwfw.example.
• Subject line: Claim – PRO 7714-882039 – Acme Logistics – $8,412.36
• Bundle order: cover letter → claim amount worksheet → evidence index → Exhibits A–G in order.
• Expected acknowledgment: 30 days per Carmack; calendar follow-up at day 28 if no response.