/vertical-logistics

name: vertical-logistics
description: Domain knowledge for the logistics & supply-chain vertical (SMB shipping & inventory) so architect and pm don't spec naively. Covers the vocabulary (TMS vs WMS, multi-carrier rate shopping, dimensional weight, BOL/ASN, lot/batch, reorder point), the non-obvious rules incumbents get right, what a naive build gets wrong, and the entities each of the four products (shipment-tracking, warehouse-lite, route-optimization, po-mgmt) must model. Applied by architect when writing ARCH-{slug}.md and by pm when writing PLAN-{slug}.md for any logistics product.
when_to_use: |
  Apply when:
  - architect writes ARCH-{slug}.md for shipment-tracking, warehouse-lite, route-optimization, or po-mgmt
  - pm writes PLAN-{slug}.md and needs to scope logistics work without underestimating carrier/inventory complexity
  - any spec touches shipments, carriers, tracking, warehouses, inventory, purchase orders, or routes
  Do NOT apply to non-logistics products (use the matching vertical skill instead).
effort: low
allowed-tools: Read, Write, Grep, Glob
paths:
  - "docs/architecture/**"
  - "docs/plans/**"
  - "docs/design/**"

Vertical: Logistics & supply chain — spec it like you've shipped a pallet

SMB shipping & inventory has a deep vocabulary and a pile of rules that look optional until a real customer's data hits them. The incumbents (ShipHero, CartonCloud, Descartes ShipRush, GoFreight, AfterShip, FreightPOP) encode decades of this. A naive spec models a "shipment" as a tracking number and a "warehouse" as a quantity column — and ships a toy. This skill is the domain framing so architect/pm don't.

The four products and their incumbents:

| Product | Archetype | Wedge | Closest incumbent | |---|---|---|---| | shipment-tracking | dashboard | branded customer-facing tracking | AfterShip (lite) | | warehouse-lite | crud | small-warehouse WMS | ShipHero / CartonCloud | | route-optimization | booking | multi-stop route optimization | Descartes / FreightPOP | | po-mgmt | crud | purchase-order lifecycle | GoFreight / FreightPOP |

1. Domain vocabulary (use these terms in the spec, not paraphrases)

• **TMS vs WMS** — Transportation Management System (moving goods between places:

carriers, rates, routes, tracking) vs Warehouse Management System (goods at rest inside a building: SKUs, locations, pick/pack/ship). Don't conflate them; route-optimization + shipment-tracking are TMS-flavoured, warehouse-lite is WMS, po-mgmt straddles.

• **Multi-carrier** — a shipment can go via USPS / UPS / FedEx / DHL / regional carriers.

Each has its own API, label format, status codes, and webhook shape.

• **Rate shopping** — given a parcel, query carriers and pick cheapest/fastest meeting the

SLA. Drives carrier choice; depends on dimensional weight.

• **Zones** — carrier distance bands (origin→dest); rate is a function of zone × weight.
• **Dimensional weight (DIM)** — billable weight = max(actual weight, L×W×H / DIM divisor).

A big light box bills as if heavy. Ignoring DIM under-quotes every rate.

• **BOL (Bill of Lading)** — the carrier contract / receipt for a shipment (esp. freight).
• **ASN (Advance Ship Notice)** — supplier's heads-up of an inbound shipment; feeds

receiving so the warehouse knows what's arriving before it lands.

• **SKU + lot/batch** — SKU identifies the product; lot/batch identifies a specific

production run (expiry, recall, FIFO). Same SKU, different lots, are not interchangeable.

• **Pick / pack / ship** — the outbound fulfilment sequence inside a warehouse.
• **Putaway** — placing received inventory into its storage location.
• **Cycle count** — periodic partial inventory audit (vs full physical count); keeps

on-hand honest without shutting the warehouse.

• **Reorder point + safety stock + lead time** — reorder when on-hand ≤ (demand ×

lead-time) + safety stock. Drives PO creation timing.

• **3PL** — third-party logistics provider; runs the warehouse/shipping on behalf of others.
• **PO → receiving → put-away** — the inbound lifecycle: order goods, receive against the

PO, put away into locations.

• **Dropship** — supplier ships direct to the end customer; inventory never touches your

warehouse.

• **Last-mile** — final leg to the customer's door; where most delivery cost/failure lives.
• **Proof of delivery (POD)** — signature / photo / timestamp confirming delivery.
• **SLA / transit time** — promised delivery window; the constraint rate-shopping optimises

against.

2. Non-obvious domain rules (the ones incumbents get right)

• **Tracking is multi-carrier with NORMALIZED statuses.** Every carrier's webhook payload

and status vocabulary differs ("In Transit" vs "MV" vs "departed facility"). You must map each carrier's raw events onto ONE normalized status enum (e.g. `pending → info_received → in_transit → out_for_delivery → delivered / exception`). The normalized timeline is the product; the raw event is provenance.

• **Branded tracking is the low-switching customer-facing wedge.** The shipper's customers

see a branded tracking page instead of the carrier's. Cheap to switch to, sticky once adopted — it's the AfterShip-lite entry point. (See shipment-tracking below.)

• **Route-optimization is a real VRP** (Vehicle Routing Problem), not "sort stops by

distance". Capacity, time windows, vehicle count, and service times make it NP-hard. **Defer the algorithm to [[geo-routing-engineer]]** — this skill only frames the domain and the entity shape; do not let the spec hand-roll the solver.

• **Dimensional weight drives cost.** Any rate-shopping or quoting feature that ignores DIM

produces wrong prices. Capture L×W×H on every parcel.

• **Warehouse needs lot/batch + cycle counts**, not just a quantity integer. Recalls,

expiry (FIFO/FEFO), and audit honesty all require lot granularity and periodic counts.

• **PO lifecycle = create → approve → receive → reconcile.** A PO isn't a row that flips to

"done"; it accrues