Larkspur Systems · Product
Product requirements
PRD-024: Route optimisation suggestions for dispatchers
Suggest a reordered day for each technician that cuts drive time, and let the dispatcher accept, edit, or ignore it in one action.
Requirements index
Goals
- BG-001 Reduce drive time per completed job
- BG-002 Increase jobs completed per technician-day
- UG-001 Dispatchers plan a day in minutes, not an hour
- UG-002 Technicians get a day that makes geographic sense
Features
- FEAT-001 Daily route suggestion (BG-001, BG-002, UG-001)
- FEAT-002 One-action accept and per-job edit (UG-001, UG-002)
- FEAT-003 Suggestion outcome reporting (BG-001)
- OUT-001 Automatic re-routing during the day
- OUT-002 Multi-day and multi-depot optimisation
User stories
- US-001 See a suggested order for tomorrow (FEAT-001)
- US-002 Understand why the suggestion differs (FEAT-001)
- US-003 Accept, edit, or ignore in one place (FEAT-002)
- US-004 See whether suggestions helped (FEAT-003)
Functional requirements
- FR-001 Generate a suggestion per technician-day (US-001)
- FR-002 Respect hard constraints (US-001)
- FR-003 Explain each moved job (US-002)
- FR-004 Accept, partial accept, dismiss (US-003)
- FR-005 Record outcome of each suggestion (US-004)
- FR-006 Workspace flag and opt-out (FEAT-001)
Non-functional
- NFR-001 Suggestion latency (FEAT-001)
- NFR-002 Location data handling (FEAT-001)
- NFR-003 Accessibility of the suggestion view (FEAT-002)
Other
- DR-001 Diff-style presentation (FR-003)
- DEP-001 Drive-time matrix provider (FR-001)
- RISK-001 Dispatchers distrust and ignore suggestions (FEAT-002)
- RISK-002 Provider cost at scale (DEP-001)
- GAP-001 Handling of technician preferences (FR-002)
- GAP-002 Suggestion timing for overnight-planned regions (FR-001)
- ASM-001 Address quality is sufficient (FR-001)
- ASM-002 Dispatchers plan the evening before (FR-001)
Executive summary
Dispatchers in mid-sized field-service companies build each technician's day by hand, in an order that reflects when jobs were booked rather than where they are. Interviews and drive-time data show technicians spend a median 31% of their working day driving, and that a reordering that respects every existing constraint would cut that to roughly 22%. This PRD specifies a nightly suggestion per technician-day, a diff view that explains each change, one-action acceptance with per-job editing, and reporting that shows whether accepted suggestions delivered the saving. Success is a 20% reduction in drive minutes per completed job in flagged workspaces within two quarters of release.
Background and context
Larkspur Dispatch schedules jobs into technician days; the order within a day is set by the dispatcher dragging jobs in the day view. Nothing in the product evaluates whether that order is geographically sensible. In August 2026 Product interviewed 14 dispatchers across 9 customers (RES-024) and analysed 6 weeks of completed routes for 1,300 technicians.
31%
Median share of the day spent driving
9%
Drive-time reduction available with existing constraints (median)
48 min
Median time a dispatcher spends ordering one day for 25 technicians
3 of top 5
Competitors offering route suggestions
Eleven of fourteen dispatchers said ordering is "the part I would hand off first". The remaining three worried a tool would override local knowledge (a customer who is never home before 10:00, a bridge closed on Tuesdays). The design in this PRD therefore suggests rather than applies, explains every change, and keeps every existing constraint hard.
Target users
Dispatcher (primary)
Plans 15 to 60 technician-days each evening; desktop, two monitors
- Needs to finish planning in under 20 minutes
- Trusts a suggestion only if the reason is visible
- Must keep promises made to customers (arrival windows)
Technician (secondary)
Receives the day on the mobile app; 6 to 10 jobs
- Wants a day that does not zigzag
- Needs the first job near home and the last near the depot on parts days
- Will not read explanations; sees only the final order
Operations manager (secondary)
Owns fleet cost and jobs-per-day targets across regions
- Needs evidence the feature saves drive time before rolling it out
- Compares regions and dispatchers
Goals and success metrics
Business goals
BG-001
Reduce drive time per completed job
- KPI
- Drive minutes per completed job, from technician location traces
- Success criteria
- 20% reduction in flagged workspaces versus the same workspaces' trailing 8-week baseline, within two quarters of release
BG-002
Increase jobs completed per technician-day
- KPI
- Completed jobs per technician-day
- Success criteria
- Median increase of 0.5 jobs per day in flagged workspaces; no increase in late arrivals
User goals
UG-001
Dispatchers plan a day in minutes, not an hour
- User benefit
- Planning time for 25 technicians drops from 48 minutes to under 15
- Pain point addressed
- Manual drag-ordering with no feedback on quality
UG-002
Technicians get a day that makes geographic sense
- User benefit
- Fewer back-and-forth legs; predictable first and last stops
- Pain point addressed
- Days ordered by booking time rather than location
Feature scope
In scope
FEAT-001
Daily route suggestion
- Description
- For each technician-day that has two or more jobs, compute an order that minimises predicted drive time while satisfying all existing constraints, and present it to the dispatcher as a suggestion.
- User impact
- Dispatchers start from a good order instead of a chronological one.
- Implements
- BG-001, BG-002, UG-001
FEAT-002
One-action accept and per-job edit
- Description
- Accept a whole suggestion, accept it for some technicians, or pin individual jobs and re-run.
- User impact
- Local knowledge is preserved; the tool never overrides a dispatcher.
- Implements
- UG-001, UG-002
FEAT-003
Suggestion outcome reporting
- Description
- Compare predicted and actual drive time for accepted and dismissed suggestions, per workspace, region, and dispatcher.
- User impact
- Operations managers can see whether the feature delivers before widening rollout.
- Implements
- BG-001
Out of scope
OUT-001
Automatic re-routing during the day
- Reason
- Requires live traffic, technician consent to mid-day changes, and customer re-notification; a different trust problem.
- Future consideration
- Revisit after two quarters of outcome data from FEAT-003.
OUT-002
Multi-day and multi-depot optimisation
- Reason
- Fewer than 8% of workspaces run more than one depot; the single-day problem captures most of the saving.
- Future consideration
- Enterprise tier, 2027 H2 at the earliest.
User stories
US-001
As a dispatcher, I want to see a suggested order for each technician's day tomorrow so that I start from a good plan instead of building one.
Critical- Implements
- FEAT-001
- AC1Opening tomorrow's day view shows a "Suggested order" panel for every technician with two or more jobs.
- AC2The panel shows predicted drive minutes for the current order and for the suggestion.
- AC3If no better order exists, the panel says so rather than showing an identical suggestion.
US-002
As a dispatcher, I want to see why each job moved so that I can judge the suggestion against what I know about the customer.
High- Implements
- FEAT-001
- AC1Each moved job shows its old and new position and a one-line reason ("moved earlier: 14 min closer to previous stop").
- AC2Jobs that did not move are visually de-emphasised.
US-003
As a dispatcher, I want to accept, partly accept, or ignore a suggestion in one place so that using it is faster than not using it.
Critical- Implements
- FEAT-002
- AC1"Accept all" applies the suggestion to every technician in the view in one action and can be undone for 30 seconds.
- AC2Pinning a job and choosing "Re-suggest" returns a new suggestion within the latency in NFR-001 that keeps pinned jobs in place.
- AC3"Dismiss" hides the suggestion for that technician-day and records the dismissal.
US-004
As an operations manager, I want to see whether accepted suggestions saved drive time so that I can decide where to roll the feature out.
Medium- Implements
- FEAT-003
- AC1A report shows, per week and region, predicted and actual drive minutes for accepted, partly accepted, and dismissed suggestions.
- AC2The report can be filtered by dispatcher.
Functional requirements
FR-001
Generate a suggestion per technician-day
Critical- Implements
- US-001
- Description
- The system shall compute, for each technician-day with two or more jobs, an ordering that minimises predicted drive time using a drive-time matrix for the technician's start location, each job location, and the end location, and shall store the suggestion with its predicted saving.
- AC1Suggestions exist for 100% of eligible technician-days by 19:00 local time the evening before.
- AC2Predicted drive time for the suggestion is less than or equal to the current order's in every case.
- AC3A suggestion is regenerated within the NFR-001 latency when a job is added to or removed from the day.
FR-002
Respect hard constraints
Critical- Implements
- US-001
- Description
- The system shall never suggest an order that violates a customer arrival window, a technician shift boundary, a job dependency ("after parts pickup"), or a job pinned by the dispatcher.
- AC1A test suite of 500 historical days with known constraints produces zero violations.
- AC2When no order satisfies all constraints, no suggestion is produced and the panel states which constraint could not be met.
FR-003
Explain each moved job
High- Implements
- US-002
- Description
- The system shall attach to each moved job a reason from a fixed vocabulary (closer to previous stop, fits arrival window, avoids backtracking, shift end) and the minutes saved or cost by the move.
- AC1Every moved job in the panel has a reason and a signed minute value.
- AC2Reasons are available through the API on the suggestion resource.
FR-004
Accept, partial accept, dismiss
Critical- Implements
- US-003
- Description
- The system shall let a dispatcher accept a suggestion for all technicians in view or for one technician, pin any job and request a new suggestion, or dismiss the suggestion; accepting shall reorder the day exactly as shown and notify technicians through the existing schedule-change path.
- AC1Accept all for 40 technicians completes in one request and one undoable action.
- AC2Technician notifications are sent once per changed day, not once per moved job.
FR-005
Record the outcome of each suggestion
Medium- Implements
- US-004
- Description
- The system shall record, per suggestion, its disposition (accepted, partly accepted, dismissed, expired), predicted drive time, and actual drive time from location traces once the day is complete.
- AC1The outcome report reconciles 100% of suggestions within 24 hours of the day's end.
- AC2Actual drive time is computed with the same method as the baseline in BG-001.
FR-006
Workspace flag and opt-out
High- Implements
- FEAT-001
- Description
- The system shall enable suggestions per workspace through a flag and shall let a workspace admin exclude individual technicians or regions.
- AC1With the flag off, no suggestions are computed or shown and no provider calls are made.
- AC2Excluded technicians never appear in the suggestion panel or the outcome report.
Non-functional requirements
NFR-001
Suggestion latency
Performance- Implements
- FEAT-001
- Description
- Interactive re-suggestion after pinning or editing shall complete quickly enough to feel like part of the drag interaction.
- Measurable criteria
- Under 3 seconds for 95% of technician-days with up to 12 jobs; under 8 seconds for 99% up to 20 jobs. Nightly batch for a 60-technician workspace completes within 10 minutes.
NFR-002
Location data handling
Security- Implements
- FEAT-001
- Description
- Job and technician locations sent to the drive-time provider shall be limited to coordinates rounded to 4 decimal places with no identifiers, and technician home addresses shall not be stored by the provider.
- Measurable criteria
- Provider contract prohibits retention; outbound payloads are logged and audited quarterly; a sampled audit finds zero identifiers.
NFR-003
Accessibility of the suggestion view
Usability- Implements
- FEAT-002
- Description
- Accept, pin, re-suggest, and dismiss shall be operable by keyboard and announced by screen readers; moved-job indicators shall not rely on colour alone.
- Measurable criteria
- WCAG 2.2 AA on the day view with suggestions enabled, verified by the accessibility checklist before beta.
Design requirements
DR-001
Diff-style presentation
- Implements
- FR-003
- Description
- The suggestion is shown beside the current order as a two-column diff with connecting lines for moved jobs, predicted minutes under each column, and reasons on hover and on focus. Unchanged jobs are muted. The panel collapses to a single column with inline move badges below 1,100 px.
External dependencies
DEP-001
Drive-time matrix provider
- Description
- A service that returns predicted drive times between up to 25 points, with time-of-day traffic profiles, for the regions Larkspur serves.
- Impact
- Without it no suggestions are produced; the day view falls back to current behaviour.
- Risk level
- Medium
- Mitigation
- Cache matrices per day; degrade to straight-line estimates with a visible "estimated" label if the provider is unavailable for more than 10 minutes.
- Implements
- FR-001
Risk assessment
RISK-001
Dispatchers distrust and ignore suggestions
High impact- Risk
- Three of fourteen interviewed dispatchers expect the tool to miss local knowledge. If early suggestions violate an unwritten rule, adoption stalls.
- Likelihood
- Medium
- Impact
- High: BG-001 and BG-002 depend on acceptance.
- Mitigation
- Suggest, never apply; explain every move (FR-003); pins persist across days; beta with the eleven receptive dispatchers first.
- Contingency
- If acceptance is under 30% after six weeks of beta, add per-customer notes as soft constraints before general availability.
- Related
- FEAT-002, FR-004
RISK-002
Provider cost at scale
Medium impact- Risk
- Matrix calls for 1,300 technicians with re-suggestions could exceed the budgeted provider spend.
- Likelihood
- Medium
- Impact
- Medium: margin, not function.
- Mitigation
- Daily matrix cache; re-suggest reuses the cached matrix; cap interactive re-suggestions at 20 per technician-day.
- Contingency
- Negotiate volume pricing or switch to an open routing engine for the nightly batch.
- Related
- DEP-001, NFR-001
Gaps and open questions
GAP-001
Handling of technician preferences
Open- Gap
- Some technicians prefer to start far from home and work back. Is that a hard constraint, a soft preference, or ignored in v1?
- Options
- Ignore in v1; per-technician "end near home" toggle; full preference model.
- Impact
- Affects FR-002 and the constraint test suite.
- Decision needed by
- 2026-09-23, Dana Okafor with Support
GAP-002
Suggestion timing for overnight-planned regions
Open- Gap
- Two customers plan at 05:00 for the same day. The 19:00 nightly batch (FR-001 AC1) does not fit them.
- Options
- Per-workspace batch time; on-demand generation when the day view opens.
- Impact
- On-demand generation raises the NFR-001 batch requirement to interactive.
- Decision needed by
- 2026-09-30, Ines Fontaine
Assumptions
ASM-001
Address quality is sufficient
- Assumption
- At least 97% of job addresses geocode to within 100 m; the remainder are flagged and excluded from suggestions rather than routed wrongly.
- Impact if wrong
- Suggestions move jobs for the wrong reasons and trust drops (RISK-001).
- Validation
- Yuki Tanabe to geocode the trailing 8 weeks of jobs in the beta workspaces and report the confidence distribution by 2026-09-20.
- Related
- FR-001, FR-002
ASM-002
Dispatchers plan the evening before
- Assumption
- Most workspaces finalise tomorrow's plan between 16:00 and 20:00 local time, so a 19:00 batch is available when it is needed.
- Impact if wrong
- Suggestions arrive after planning is done and are ignored.
- Validation
- Usage logs of day-view edits by hour, per workspace, from the last quarter; see GAP-002 for the known exceptions.
- Related
- FR-001