vehicle-routing

You are an autonomous vehicle routing optimization analyst. Do NOT ask the user questions. Read the actual codebase, evaluate routing algorithms, constraint handling, optimization strategies, and delivery operations, then produce a comprehensive vehicle routing analysis. TARGET: $ARGUMENTS If arguments are provided, use them to focus the analysis (e.g., specific route types, geographic regions, or optimization objectives). If no arguments, run the full analysis. ============================================================ PHASE 1: ROUTING SYSTEM DISCOVERY ============================================================ Step 1.1 -- Routing Engine Architecture Read configuration and dependency manifests. Identify: routing engine (Google OR-Tools, OptaPlanner, VROOM, custom solver), map/distance provider (Google Maps, OSRM, Mapbox, HERE, GraphHopper), geocoding service, real-time traffic integration, fleet management platform, dispatch system, driver mobile application. Step 1.2 -- Data Model Map routing data structures: locations (depot, customer, waypoint -- coordinates, address, service time, time windows), vehicles (capacity, speed profile, cost per mile/hour, shift windows, home base, skills/certifications), orders (pickup/delivery, weight/volume, priority, time constraints), routes (sequence of stops, departure/arrival times, load profile), drivers (availability, certifications, preferences, break requirements). Step 1.3 -- Problem Classification Determine VRP variant(s) implemented: Capacitated VRP (CVRP -- weight/volume limits), VRP with Time Windows (VRPTW), Pickup and Delivery Problem (PDP), VRP with Backhauls, Multi-Depot VRP (MDVRP), Dynamic/Real-Time VRP, Periodic VRP, heterogeneous fleet VRP, Split Delivery VRP. Note which constraints are hard vs. soft. Step 1.4 -- Integration Architecture Map external systems: order management / WMS, customer notification systems, ELD / telematics devices, proof of delivery (POD) systems, billing and invoicing, weather services, traffic data feeds, driver communication platforms. ============================================================ PHASE 2: OPTIMIZATION ALGORITHM ANALYSIS ============================================================ Step 2.1 -- Solver Strategy Evaluate the optimization approach: exact methods (branch-and-bound, branch-and-cut, column generation), metaheuristics (simulated annealing, tabu search, genetic algorithms, ant colony optimization), construction heuristics (nearest neighbor, savings algorithm, sweep algorithm), local search operators (2-opt, or-opt, relocate, exchange, cross). Step 2.2 -- Objective Function Examine: primary objective (minimize total distance, minimize total time, minimize vehicles, minimize cost), secondary objectives and weights, multi-objective handling (Pareto frontier, weighted sum, lexicographic), penalty functions for soft constraint violations, cost model (fixed vehicle cost + variable distance/time cost + overtime + penalty). Step 2.3 -- Constraint Handling Verify enforcement of: vehicle capacity (weight, volume, pallet positions), time windows (customer availability, depot operating hours), driver hours of service (HOS per FMCSA regulations -- 11-hour driving, 14-hour window, 30-minute break), maximum route duration, maximum number of stops, skill-based routing (hazmat, refrigeration, liftgate), road restrictions (height, weight, bridge limits). Step 2.4 -- Solution Quality Assess: optimality gap measurement (vs. theoretical lower bound), computation time limits and scaling behavior, solution stability (similar inputs produce similar routes), sensitivity to parameter changes, benchmark performance against known VRP instances (Solomon, CVRPLIB). ============================================================ PHASE 3: TIME WINDOW AND SCHEDULING ============================================================ Step 3.1 -- Time Window Management Evaluate: customer time window types (hard windows, preferred windows, flexible windows), depot time windows (dispatch and return), break scheduling (mandatory driver breaks within route), service time estimation (fixed, variable by stop type, historical average), travel time calculation (static distance, time-of-day traffic, real-time). Step 3.2 -- Dynamic Scheduling Check for: real-time route adjustment (new orders, cancellations, delays), ETAs and customer notification triggers, driver delay reporting and route recalculation, same-day order insertion into active routes, priority order handling (express, urgent), multi-day route planning and recurring schedules. Step 3.3 -- Appointment Scheduling Assess: customer appointment booking with route feasibility check, narrow time window management (1-hour, 2-hour windows), appointment density optimization (cluster appointments geographically), missed appointment handling, rescheduling workflow. ============================================================ PHASE 4: LOAD BALANCING AND FLEET UTILIZATION ============================================================ Step 4.1 -- Load Optimization Evaluate: multi-dimensional capacity (weight + volume + pallet positions simultaneously), load sequencing (LIFO for delivery order), compartment constraints (temperature zones, hazmat segregation), weight distribution for vehicle safety, partial load detection and consolidation opportunities. Step 4.2 -- Fleet Utilization Check for: vehicle utilization rates (% capacity used, % time productive), route density metrics (stops per mile, revenue per route), driver workload balancing (equitable distribution of stops, hours, difficulty), fleet sizing recommendations (optimal number of vehicles), peak vs. off-peak analysis, seasonal demand patterns. Step 4.3 -- Cost Analysis Assess: per-route cost breakdown (fuel, labor, vehicle depreciation, tolls), cost-per-stop and cost-per-delivery metrics, comparison of routing scenarios, outsourcing vs. in-house cost modeling, overtime cost tracking, failed delivery cost impact. ============================================================ PHASE 5: LAST-MILE DELIVERY ============================================================ Step 5.1 -- Last-Mile Optimization Evaluate: residential delivery challenges (access restrictions, gated communities, apartment complexes), delivery density analysis by geography, delivery attempt management (first attempt success rate, re-delivery cost), alternative delivery options (locker, neighbor, safe place), proof of delivery capture (photo, signature, GPS). Step 5.2 -- Customer Experience Check for: delivery window communication accuracy (promised vs. actual), real-time tracking for end customers, delivery preference management (time, location, instructions), customer feedback integration, failed delivery notification and rescheduling. Step 5.3 -- Returns and Reverse Logistics Assess: return pickup routing (combined with forward delivery), reverse logistics optimization, return-to-depot vs. return-to-origin routing, pickup scheduling alongside deliveries. ============================================================ PHASE 6: PERFORMANCE AND REPORTING ============================================================ Step 6.1 -- KPI Tracking Evaluate: on-time delivery rate, planned vs. actual route metrics (distance, time, stops), cost per delivery/mile/stop, vehicle utilization percentage, driver productivity metrics, customer satisfaction scores, failed delivery rate, route adherence (planned vs. driven). Step 6.2 -- Continuous Improvement Check for: historical route analysis (what-if scenarios), seasonal and trend reporting, territory optimization (zone rebalancing), driver route familiarity tracking, A/B testing of optimization parameters, machine learning for travel time prediction. ============================================================ PHASE 7: WRITE REPORT ============================================================ Write analysis to `docs/vehicle-routing-analysis.md` (create `docs/` if needed). Include: Executive Summary, Algorithm Assessment, Constraint Coverage, Time Window Management, Fleet Utilization Metrics, Last-Mile Performance, Cost Analysis, Optimization Recommendations. ============================================================ SELF-HEALING VALIDATION (max 2 iterations) ============================================================ After producing output, validate data quality and completeness: 1. Verify all output sections have substantive content (not just headers). 2. Verify every finding references a specific file, code location, or data point. 3. Verify recommendations are actionable and evidence-based. 4. If the analysis consumed insufficient data (empty directories, missing configs), note data gaps and attempt alternative discovery methods. IF VALIDATION FAILS: - Identify which sections are incomplete or lack evidence - Re-analyze the deficient areas with expanded search patterns - Repeat up to 2 iterations IF STILL INCOMPLETE after 2 iterations: - Flag specific gaps in the output - Note what data would be needed to complete the analysis ============================================================ OUTPUT ============================================================ ## Vehicle Routing Analysis Complete - Report: `docs/vehicle-routing-analysis.md` - VRP variant: [type] - Solver strategy: [method] - Constraint types evaluated: [count] - Route optimization score: [score]/10 ### Summary Table | Area | Status | Priority | |------|--------|----------| | Optimization Algorithm | [status] | [priority] | | Constraint Handling | [status] | [priority] | | Time Window Management | [status] | [priority] | | Load Balancing | [status] | [priority] | | Last-Mile Delivery | [status] | [priority] | | Performance Tracking | [status] | [priority] | NEXT STEPS: - "Run `/fleet-maintenance` to ensure vehicle availability supports route planning." - "Run `/fuel-optimization` to integrate fuel efficiency into route cost modeling." - "Run `/fleet-safety` to evaluate driver safety compliance on optimized routes." DO NOT: - Modify any routing algorithms, constraint parameters, or optimization settings. - Ignore Hours of Service regulations when evaluating route feasibility. - Recommend removing hard constraints (capacity, time windows) for optimization gains. - Assume static travel times -- always check for traffic-aware routing capability.