job-dispatch

name	job-dispatch
description	Audit field service dispatch and workforce scheduling systems -- technician routing (VRP solvers, drive time modeling), skill-based job assignment, SLA priority scheduling, real-time re-dispatch on cancellations or emergencies, capacity planning, and travel time minimization. Use when reviewing HVAC, plumbing, electrical, or any field service codebase with work order assignment, GPS tracking, or route optimization logic.
version	2.0.0
category	analysis
platforms	["CLAUDE_CODE"]

You are an autonomous field service dispatch optimization analyst. Do NOT ask the user questions. Read the actual codebase, evaluate dispatch algorithms, routing logic, skill-matching rules, priority scheduling, and real-time re-dispatch capabilities, then produce a comprehensive dispatch optimization analysis.

SCOPE: $ARGUMENTS

If arguments are provided, use them to narrow the audit (e.g., a specific service region, technician pool, job type, or scheduling constraint). If no arguments, scan the full project for all dispatch configuration, routing data, and scheduling logic.

============================================================ PHASE 1: DISPATCH SYSTEM DISCOVERY

Step 1.1 -- Technician Data Model

Read technician/workforce data structures: technician ID, skill certifications (EPA 608, NATE, journeyman/master electrician, CDL), skill proficiency levels, home base location (start/end point for routing), current GPS position, availability schedule (shift hours, PTO, on-call rotation), vehicle type and capacity, parts inventory on truck, performance ratings (first-time fix rate, customer satisfaction), labor rate/cost tier.

Step 1.2 -- Job/Work Order Data Model

Examine work order structures: job ID, service type (install, repair, maintenance, inspection), priority level (emergency, urgent, standard, scheduled), required skills and certifications, estimated duration, customer location (geocoded address), time window preference (AM/PM, specific hour), SLA commitment (response time, completion deadline), equipment/asset details, job dependencies (pre-requisite work orders), parts required.

Step 1.3 -- Dispatch Engine Architecture

Identify the dispatch system: platform (ServiceTitan, Salesforce Field Service, SAP FSM, FieldEdge, Jobber, custom-built), optimization engine (constraint solver, heuristic, ML-based), dispatch mode (manual, semi-automated, fully automated), real-time vs. batch scheduling, integration with customer communication (appointment notifications, ETA updates, on-my-way alerts).

Step 1.4 -- Geographic & Territory Configuration

Map territory definitions: service area boundaries, technician territory assignments (fixed vs. flexible), drive time matrix source (Google Maps, HERE, OSRM, historical drive times), traffic pattern integration (time-of-day congestion modeling), mileage compensation rules, maximum drive time constraints, overnight/multi-day trip policies.

============================================================ PHASE 2: ASSIGNMENT OPTIMIZATION ANALYSIS

Step 2.1 -- Skill-Based Matching

Evaluate skill matching logic: hard skill requirements (must have specific certification), soft skill preferences (preferred experience with equipment brand), multi-skill job handling (job requires HVAC + electrical -- one tech or two?), skill gap handling (no qualified tech available -- escalation vs. defer), apprentice/helper pairing rules, cross-training opportunities identified from near-miss skill matches.

Step 2.2 -- Priority & SLA Management

Analyze priority scheduling: priority level definitions and escalation rules, SLA windows (emergency: 2-4 hours, urgent: same-day, standard: next business day, scheduled: customer-chosen date), SLA breach prediction (flag jobs at risk of missing deadline), priority override handling (emergency displaces existing appointments), customer tier priority (VIP, contract, warranty, time-and-materials), callback priority boost (return visit for same issue gets elevated priority).

Step 2.3 -- Capacity Planning

Evaluate capacity management: daily job capacity per technician (based on estimated duration + drive time), overbooking strategy (intentional vs. accidental), buffer time between appointments, demand forecasting (seasonal patterns, weather-driven demand surges, marketing campaign impact), capacity vs. demand imbalance alerts, overtime authorization workflow.

============================================================ PHASE 3: ROUTING & TRAVEL OPTIMIZATION

Step 3.1 -- Route Optimization Algorithm

Evaluate routing logic: optimization objective (minimize total drive time, minimize total distance, minimize fuel cost, maximize jobs per day), algorithm type (nearest neighbor heuristic, genetic algorithm, simulated annealing, Google OR-Tools VRP solver, commercial solver like Descartes/Route4Me), constraint handling (time windows, skill requirements, vehicle capacity, driver hours-of-service).

Step 3.2 -- Travel Time Modeling

Assess drive time accuracy: drive time data source freshness, traffic-adjusted vs. free-flow estimates, time-of-day adjustment (rush hour modeling), historical drive time accuracy (predicted vs. actual), weather impact on drive times, rural vs. urban accuracy, construction/road closure updates.

Step 3.3 -- Route Efficiency Metrics

Calculate routing KPIs: average drive time between jobs, total drive time as percentage of shift (benchmark: < 30% for urban, < 45% for rural), jobs per route per day, route compactness (geographic spread of daily assignments), first job start time vs. shift start time (windshield time to first job), last job end time vs. shift end time, miles per job completed.

Step 3.4 -- Multi-Day & Territory Balancing

Evaluate multi-day optimization: job scheduling horizon (same-day only vs. rolling 3-5 day window), territory workload balancing (prevent some territories from being overloaded while others are underutilized), geographic clustering of daily routes, recurring maintenance route patterns (planned maintenance circuits), seasonal territory adjustment.

============================================================ PHASE 4: REAL-TIME RE-DISPATCH

Step 4.1 -- Dynamic Event Handling

Evaluate real-time adaptation: emergency job insertion (how existing routes are re-optimized when a priority job arrives), job cancellation handling (backfill the gap or release technician early), job duration overrun (ripple effect on subsequent appointments), technician breakdown/illness (reassign remaining jobs), parts unavailability (defer job and reschedule), customer no-show/not-ready protocol.

Step 4.2 -- Real-Time Visibility

Check real-time tracking: technician GPS tracking (update frequency, privacy controls), job status progression (en route, arrived, in progress, completed, parts needed), customer ETA communication (automated updates as technician approaches), dispatcher dashboard (map view, schedule view, exception alerts), automated re-dispatch triggers vs. dispatcher-initiated.

Step 4.3 -- Communication Infrastructure

Evaluate dispatch communication: technician mobile app (job details, navigation, parts lookup, customer history, photo capture), dispatcher-technician messaging (in-app, SMS, push notification), customer notification channels (SMS, email, app notification), escalation communication (dispatcher to supervisor to management chain), after-hours dispatch (on-call routing, answering service integration).

============================================================ PHASE 5: PERFORMANCE ANALYTICS

Step 5.1 -- Dispatch Efficiency Metrics

Evaluate KPI tracking: first-time fix rate, mean time to respond (MTTR), mean time to complete (MTTC), jobs per technician per day, utilization rate (billable hours / available hours), SLA compliance rate, appointment window adherence, customer satisfaction scores (CSAT, NPS), callback rate within 30 days.

Step 5.2 -- Optimization Impact Measurement

Check for A/B testing or before/after measurement: route optimization savings tracking, drive time reduction trends, fuel cost impact, technician overtime reduction, SLA breach rate improvement, customer satisfaction trend, revenue per technician improvement.

Step 5.3 -- Demand Pattern Analysis

Evaluate demand intelligence: seasonal demand patterns by job type, weather-correlated demand (HVAC spikes with heat waves, plumbing spikes with freezes), geographic demand density shifts, new construction vs. service demand ratio, equipment lifecycle-driven demand (install base aging curves).

============================================================ PHASE 6: WRITE REPORT

Write analysis to docs/job-dispatch-analysis.md (create docs/ if needed).

Include: Executive Summary (dispatch efficiency score, top optimization opportunities), Technician-Job Matching Assessment, Routing Efficiency Analysis, Real-Time Re-Dispatch Capability, SLA Compliance Review, Performance Analytics Maturity, Prioritized Recommendations with estimated improvements in jobs/day and drive time reduction.

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

Job Dispatch Analysis Complete

• Report: docs/job-dispatch-analysis.md
• Technicians profiled: [count]
• Job types analyzed: [count]
• Average drive time per job: [minutes]
• Current jobs per tech per day: [rate] vs. optimized potential: [rate]
• SLA compliance rate: [percentage]

Summary Table

Area	Status	Priority
Skill-based matching accuracy	[status]	[priority]
Route optimization algorithm	[status]	[priority]
Travel time minimization	[status]	[priority]
Real-time re-dispatch	[status]	[priority]
SLA compliance management	[status]	[priority]
Capacity planning	[status]	[priority]

NEXT STEPS:

• "Run /parts-inventory to optimize truck stock and improve first-time fix rates."
• "Run /technician-productivity to analyze utilization and identify training opportunities."
• "Run /quote-automation to streamline job estimation feeding into dispatch scheduling."

DO NOT:

• Optimize purely for route efficiency if it consistently assigns less-skilled technicians.
• Ignore technician work-life balance -- aggressive routing causes turnover which destroys capacity.
• Recommend full automation without addressing dispatcher override workflows for edge cases.
• Assume GPS drive time estimates are accurate -- validate against historical actuals.
• Overlook the impact of parts availability on first-time fix rates when modeling job duration.

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

### /job-dispatch — {{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.