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