---
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.."
version: "2.0.1"
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.