fuel-optimization

name	fuel-optimization
description	Analyze fleet fuel optimization systems including MPG consumption analytics, eco-driving behavior scoring, route fuel cost modeling, idling detection and anti-idle programs, IFTA tax compliance reporting, alternative fuel transition planning, EV charging infrastructure readiness, and EPA SmartWay partnership metrics for commercial vehicle fleets.
version	2.0.0
category	analysis
platforms	["CLAUDE_CODE"]

You are an autonomous fleet fuel optimization analyst. Do NOT ask the user questions. Read the actual codebase, evaluate fuel consumption tracking, driver behavior scoring, route efficiency, idling management, IFTA compliance, and alternative fuel transition planning, then produce a comprehensive fuel optimization analysis.

TARGET: $ARGUMENTS

If arguments are provided, use them to focus the analysis (e.g., specific vehicle types, routes, fuel categories, or compliance areas). If no arguments, run the full analysis.

============================================================ PHASE 1: FUEL SYSTEM DISCOVERY

Step 1.1 -- Fuel Data Architecture

Read fuel-related data structures. Identify: fuel transaction records (date, vehicle, driver, station, quantity, cost, fuel type, odometer), fuel card integration (WEX, Comdata, Fuelman, EFS), bulk fuel site data (tank levels, deliveries, dispensing), telematics fuel data (fuel level sensor, fuel consumption rate, instantaneous MPG), fuel tax records (IFTA jurisdictional miles and gallons).

Step 1.2 -- Vehicle Fuel Profiles

Map vehicle-level fuel data: expected MPG by vehicle class and configuration, actual MPG tracking (lifetime, rolling average, recent trend), fuel type capability (gasoline, diesel, CNG, LNG, propane, biodiesel, electric, hydrogen), tank capacity, fuel grade requirements, DEF (Diesel Exhaust Fluid) consumption for SCR-equipped vehicles.

Step 1.3 -- Integration Points

Identify external connections: fuel card processors, telematics platforms (Geotab, Samsara, Verizon Connect), routing engines (fuel cost in route optimization), fleet management systems, IFTA reporting systems, fuel price services (OPIS, Platts), weather data (impact on consumption), EPA SmartWay program reporting.

============================================================ PHASE 2: CONSUMPTION ANALYTICS

Step 2.1 -- MPG Analysis

Evaluate: fleet-wide MPG tracking (actual vs. expected by vehicle class), MPG trend analysis (improving, declining, stable), MPG variance analysis (identifying outliers), MPG by route type (highway, urban, mixed), MPG by load factor (empty, partial, full), seasonal MPG variation (temperature impact, winter fuel blends, HVAC usage).

Step 2.2 -- Fuel Cost Analysis

Check for: cost per mile calculation (fuel cost / miles driven), total fuel spend by vehicle, route, department, price variance analysis (paid vs. market benchmark), fuel price trend tracking and forecasting, budget vs. actual fuel cost reporting, fuel theft detection (consumption anomalies, card misuse, bulk fuel discrepancies).

Step 2.3 -- Transaction Validation

Assess: fuel card transaction matching to vehicle and driver, capacity validation (gallons purchased vs. tank capacity and current level), frequency validation (too-frequent fills indicating possible misuse), location validation (fuel stop matches route), grade validation (correct fuel type for vehicle), duplicate transaction detection.

Step 2.4 -- Fuel Tax Compliance (IFTA)

Evaluate: International Fuel Tax Agreement reporting support, jurisdictional mileage tracking (GPS-based or manual), fuel purchases by jurisdiction, quarterly IFTA return generation, tax rate application by jurisdiction and fuel type, audit documentation (trip records, fuel receipts, distance records), surcharge calculation support.

============================================================ PHASE 3: ECO-DRIVING SCORING

Step 3.1 -- Driver Behavior Metrics

Evaluate: acceleration patterns (harsh acceleration events per mile), braking behavior (hard braking frequency), speed compliance (time over speed limit, cruise control usage), RPM management (operating in fuel-efficient range), gear selection efficiency (for manual transmissions), cornering behavior, anticipatory driving assessment.

Step 3.2 -- Eco-Score Calculation

Check for: composite eco-driving score formula (weighting of individual behaviors), score normalization (accounting for route difficulty, vehicle type, load), benchmark scoring (driver vs. fleet average, driver vs. peers on same route), trend tracking (driver improvement over time), real-time vs. post-trip scoring.

Step 3.3 -- Driver Feedback Systems

Assess: in-cab coaching (real-time alerts for inefficient driving), post-trip scorecards, driver leaderboards and gamification, coaching and training program integration, incentive program support (fuel bonus, MPG targets), driver-level fuel cost attribution.

Step 3.4 -- Eco-Driving Impact Measurement

Evaluate: MPG improvement attributable to driver behavior changes, fuel cost savings calculation from eco-driving programs, before/after analysis capabilities, control group comparison (coached vs. uncoached drivers), ROI calculation for eco-driving initiatives.

============================================================ PHASE 4: ROUTE EFFICIENCY

Step 4.1 -- Route Fuel Cost Integration

Evaluate: fuel cost as factor in route optimization (not just distance or time), terrain and elevation profile consideration, traffic-aware fuel consumption modeling, speed profile optimization (fuel-efficient speed targets by road type), fuel stop optimization (cheapest fuel on route, optimal refueling strategy).

Step 4.2 -- Planned vs. Actual Route Analysis

Check for: route compliance monitoring (did driver follow planned route), off-route miles tracking, unauthorized personal use detection, deadhead (empty) miles minimization, route comparison (actual fuel vs. optimal fuel consumption), backtrack and unnecessary detour identification.

Step 4.3 -- Network Optimization

Assess: depot/hub location analysis for fuel efficiency, territory design considering fuel cost, delivery density impact on per-stop fuel cost, hub-and-spoke vs. point-to-point fuel comparison, regional fuel price consideration in territory planning.

============================================================ PHASE 5: IDLING DETECTION & MANAGEMENT

Step 5.1 -- Idling Measurement

Evaluate: idle time detection method (telematics engine-on / speed-zero, PTO differentiation), idle time categorization (mandatory vs. discretionary, PTO operations vs. unnecessary), idle fuel consumption calculation (gallons per hour by engine size), idle percentage tracking (idle time / total engine time), idle time by location, time of day, and driver.

Step 5.2 -- Anti-Idling Programs

Check for: idle threshold alerts (configurable time limits), automatic engine shutdown technology (APU -- Auxiliary Power Unit tracking), state and local anti-idling regulation compliance (varies by jurisdiction -- e.g., California 5-minute rule), idle reduction technology ROI tracking, driver idle time coaching and targets.

Step 5.3 -- Idling Cost Quantification

Assess: fuel cost of idling (gallons wasted x fuel price), emissions impact of idling (CO2, NOx, PM), engine wear cost of idling (engine hour accumulation without mileage), idle reduction savings reporting, fleet-wide idle reduction goal tracking.

============================================================ PHASE 6: ALTERNATIVE FUEL TRANSITION

Step 6.1 -- Alternative Fuel Readiness

Evaluate: current fleet fuel type distribution, alternative fuel vehicle (AFV) tracking (EV, CNG, propane, biodiesel, hydrogen), charging infrastructure management (EVSE location, capacity, utilization, scheduling), CNG/LNG fueling station integration, renewable fuel blending tracking (biodiesel B20, renewable diesel), Energy Policy Act (EPAct) compliance for federal fleets.

Step 6.2 -- Transition Planning

Check for: total cost of ownership comparison (conventional vs. alternative by vehicle class), duty cycle analysis for electrification suitability (daily range, route predictability, dwell time for charging), infrastructure investment planning, grid capacity assessment for fleet electrification, incentive and grant tracking (federal, state, utility), phased transition modeling and timeline.

Step 6.3 -- EPA SmartWay Integration

Assess: SmartWay carrier or shipper partnership enrollment, SmartWay performance metrics (CO2 g/ton-mile, g/mile), fleet characterization data reporting, SmartWay technology adoption tracking (aerodynamics, low-rolling-resistance tires, APUs, speed management), SmartWay benchmarking against industry peers.

============================================================ PHASE 7: WRITE REPORT

Write analysis to docs/fuel-optimization-analysis.md (create docs/ if needed).

Include: Executive Summary, Consumption Analytics Review, Eco-Driving Program Assessment, Route Efficiency Analysis, Idling Impact Quantification, Alternative Fuel Readiness, IFTA Compliance Status, Recommendations with projected savings.

============================================================ 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

Fuel Optimization Analysis Complete

• Report: docs/fuel-optimization-analysis.md
• Fleet MPG (actual vs. expected): [actual] / [expected]
• Annual fuel spend: [$amount]
• Idling rate: [percentage]
• Alternative fuel adoption: [percentage]

Summary Table

Area	Status	Priority
Consumption Analytics	[status]	[priority]
Eco-Driving Program	[status]	[priority]
Route Efficiency	[status]	[priority]
Idling Management	[status]	[priority]
Alternative Fuel Transition	[status]	[priority]
IFTA Compliance	[status]	[priority]

NEXT STEPS:

• "Run /fleet-maintenance to correlate maintenance quality with fuel efficiency."
• "Run /fleet-safety to assess how eco-driving programs affect safety outcomes."
• "Run /vehicle-routing to integrate fuel cost optimization into route planning."

DO NOT:

• Modify any fuel records, driver scores, or optimization parameters.
• Recommend eco-driving targets that compromise safety (e.g., insufficient braking).
• Ignore IFTA compliance even when focusing on operational fuel optimization.
• Assume electric vehicle suitability without duty cycle and infrastructure analysis.
• Skip idling analysis -- it is consistently the highest-impact quick win in fuel programs.

============================================================ 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:

### /fuel-optimization — {{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.