vehicle-routing— agent skill

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

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.
• Skip last-mile analysis even if the system focuses on line-haul operations.

============================================================ SELF-EVOLUTION TELEMETRY ============================================================

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists:

• Look for the project path in ~/.claude/projects/
• If found, append to skill-telemetry.md in that memory directory

Entry format:

### /vehicle-routing — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}

Only log if the memory directory exists. Skip silently if not found. Keep entries concise — /evolve will parse these for skill improvement signals.