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.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
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).
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.
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 received quantities (often partial, across multiple receipts) and is
reconciled against the invoice. Skipping receive/reconcile makes the PO a sticky note.
3. What a naive build gets wrong
Single-carrier tracking โ hardcodes one carrier; real shippers use several.
Un-normalized carrier statuses โ stores raw carrier strings, so the UI and any
automation can't reason across carriers. Normalize on ingest.
Route-opt as nearest-neighbour โ greedy nearest-stop gives bad routes and ignores
capacity/time-windows. It's VRP โ [[geo-routing-engineer]].
Inventory without lot/batch or cycle count โ a bare quantity column can't do
recalls, expiry, or audit; on-hand drifts and nobody trusts it.
PO without receiving/reconciliation โ no partial receipts, no invoice match; the PO
is decorative.
Ignoring dimensional weight in rate shopping โ quotes are systematically too low;
margins evaporate on bulky-light parcels.
4. Must-model entities (the shapes that prevent rework)
Pair these with [[migration-ready-schema]] (source_ref + import_batch_id on importable
entities; model carriers/suppliers/customers as their own tables, not inline fields).
Shipment โ carrier (FK) + a normalized status + a tracking-event timeline
(ordered events, each with carrier-raw payload + normalized status + timestamp + location).
Parcel dims (LรWรH + weight) for DIM. POD reference.
InventoryItem โ SKU (FK) + lot/batch + location (bin/shelf, its own entity) +
on-hand qty + cycle-count records (counted qty, variance, timestamp, counter).
PurchaseOrder โ full lifecycle: create โ approve โ receive โ reconcile. Line items
with ordered vs received qty (partial receipts โ a Receipt entity), supplier (FK),
reconciliation against invoice.
Route โ ordered stops + constraints (vehicle capacity, time windows, service
time per stop). Hand the optimisation algorithm to [[geo-routing-engineer]] โ the
spec defines the entity and constraints, not the solver.
5. Per-product notes (wedge + the one domain thing)
shipment-tracking (dashboard) โ wedge: branded customer-facing tracking page
(AfterShip-lite, low switching cost). The one thing: multi-carrier ingestion with
normalized status mapping โ every carrier's webhook normalized onto one enum.
Carrier/tracking ingestion โ [[connector-builder]].
warehouse-lite (crud) โ wedge: small-warehouse WMS for shops outgrowing
spreadsheets. The one thing:lot/batch + location + cycle count โ inventory is not
a quantity column.
route-optimization (booking) โ wedge: multi-stop route optimization; highest
value, hardest.The one thing: it's a real VRP โ model stops + constraints here,
but the solver is [[geo-routing-engineer]]'s. Do not ship nearest-neighbour.
po-mgmt (crud) โ wedge: purchase-order management. The one thing: the full
create โ approve โ receive โ reconcile lifecycle with partial receipts, not a status
flag.
6. Compliance (light โ flag, don't over-build)
Carrier ToS โ each carrier API has terms on caching/displaying tracking data and
branding. Respect them; don't scrape where an API exists.
Hazmat โ if shipping dangerous goods, special labelling/declaration applies. Flag if
in scope; defer the heavy ruleset.
Customs (cross-border) โ commercial invoice, HS codes, duties for international
parcels. Capture the basics (declared value, HS code) if cross-border is in scope;
defer heavy customs brokerage logic.
Proof-of-delivery retention โ PODs (signatures/photos) are dispute evidence; retain
them per the shipper's policy and don't expire them early.
