Meridian Field Services · Dispatch Modernization: instructional example, not project evidence
What this document specifies, where it sits in the chain, and how to read it. Identifiers here are the one place system notation belongs in body content.
This document specifies the assignment-recommendation behavior of the dispatch board, the feature committed in the project PRD[1] and justified by the dispatch-board business case[2]. Behavior statements are numbered FR-nnn; acceptance criteria AC-nnn reference their parent statement; error catalog entries are ERR-nn. Verification methods come from a closed set: inspection (read it), analysis (calculate it), demonstration (watch it), test (automate it).
Who may do what. Denial is behavior too: every "may not" row has a defined refusal in the error catalog.
| Action | Dispatcher | Operations manager | Field technician |
|---|---|---|---|
| Request recommendations for a job | Yes | No: ERR-04 | No: ERR-04 |
| Accept a proposed assignment | Yes | No: ERR-04 | No: ERR-04 |
| Override with a different technician | Yes | No: ERR-04 | No: ERR-04 |
| View recommendation & override history | Own hub | All hubs | Own assignments only |
Roles reuse the project's role definitions by reference; this requirement invents no local roles.
The atomic behavior statements. Each carries its identifier, priority, fit criterion (the one-sentence way to prove it false), and how it will be verified. One behavior per statement; the system is always the subject.
| ID | The system shall… | Priority | Fit criterion | Verify |
|---|---|---|---|---|
| FR-010 | propose exactly three candidate technicians for each new job, ranked by suitability | Must | Three candidates render in every case, or the defined shortfall behavior (§4) applies | test |
| FR-011 | display, per candidate, the plain-language reasons for the ranking | Must | Every proposal renders at least two reasons a dispatcher recognizes as true | demonstration |
| FR-012 | record every override together with the dispatcher's selected reason | Must | An override without a stored reason cannot complete | test |
| FR-013 | exclude unqualified technicians from proposals entirely, never merely down-rank them | Must | No proposal ever contains a technician lacking the job's required skill | test |
Each statement traces to a business requirement in the dispatch-board case[2]; statements name no services, components, or vendors: that freedom belongs to engineering.
The ranking rule with every branch closed. "To be decided" is not a branch outcome; the template rejects open branches. Worked examples are part of the specification.
Suitability ranking. Qualification is a gate, not a weight: unqualified candidates are excluded first (FR-013). Qualified candidates then rank by weighted score: 50% proximity band + 30% calendar availability + 20% response-window urgency; weights are fixed in this version. Proximity bands (historical drive time): A under 10 minutes, B 10 to 20, C 20 to 40, D over 40. Ties break on earlier availability, then employee number. One or two qualified: propose all who qualify with a shortfall notice (ERR-06). Zero qualified: ERR-02.
The interaction as a sequence diagram and the assignment lifecycle as a state diagram, both produced through Specira's diagram service, the same path exports use. The numbered steps under each diagram are its accessibility fallback. Exception flows here and the error catalog in §8 must agree; the template checks that they do.
Fallback: 1 Dana creates the job → 2 candidates requested → 3 within 2 s, ranked candidates render with reasons (fewer than three carries the ERR-06 shortfall notice; late falls to the full list, ERR-01) → 4 Dana accepts, or overrides with a reason code (FR-012) → 5 assignment recorded, idempotent by job id → 6 Marcus notified and confirms. Postcondition: exactly one active assignment for the job.
Fallback: Created → Proposed (candidates rendered) → Assigned (accept or stored-reason override) → In Progress (technician confirms) → Completed. Created reaches Assigned directly on the manual path (ERR-01); Assigned returns to Proposed through Returned when a no-show is flagged.
What must be true of the data: meaning, validation, and what the user experiences on failure. Storage design (keys, tables, indexes) is deliberately absent.
| Data element | Required | Validation | On failure |
|---|---|---|---|
| Job skill requirement | Yes | One of the governed skills taxonomy (taxonomy[6]) | Hard rejection: ERR-03 |
| Site location | Yes | Resolvable to coordinates | Warning; manual placement allowed |
| Technician status | From tracking feed | At most five minutes stale | Candidate flagged "location uncertain"; ranking proceeds without proximity |
Operations at behavior altitude. Every state-changing operation answers the retry question explicitly; a blank idempotency cell fails validation.
| Operation | Input → output | State-changing | Retry safety | Errors |
|---|---|---|---|---|
| Recommendation request | Job identifier → ranked candidates with reasons | No | Always safe (read-only) | ERR-01 · ERR-02 · ERR-03 |
| Assignment acceptance | Proposal → recorded assignment + notification | Yes | Idempotent by job identifier: repeating the same acceptance returns the original result, creates nothing new | ERR-04 · ERR-05 |
Every failure with its defined response: four fields per entry, none blank. The catalog is checked against flows, validations, and interfaces above: a negative path defined anywhere must appear here.
| ID | Trigger | System response | Message class | Class |
|---|---|---|---|---|
| ERR-01 | Recommendation exceeds response threshold | Render full technician list immediately; flow continues manually | Informational | recoverable |
| ERR-02 | No qualified technician for the job's skill | Shortfall notice naming the unmet skill | Action needed | recoverable |
| ERR-03 | Unknown skill value on job | Rejection naming the offending value | Correction | recoverable |
| ERR-04 | Actor lacks permission | Standard denial; event logged | Denial | terminal for actor |
| ERR-05 | Assignment attempted via retired legacy screen after cutover | Rejection pointing to the board (§13) | Correction | terminal |
| ERR-06 | Qualified shortfall: only one or two candidates hold the required skill | Propose all who qualify; shortfall notice names the count and the missing skill (§4) | Informational | recoverable |
Degradation: the mechanism, not a promise. The board keeps the last-received technician list client-side; if the recommendation service or the tracking feed is unavailable, it falls back to manual assignment against that local list, visibly flagged as degraded. With only the tracking feed absent, proximity leaves the ranking and candidates are flagged "location uncertain." The board never blanks because the fallback list is already local; no network round-trip stands between Dana and an assignment.
Rules link to their governed knowledge-base entries with the behavioral consequence stated here; thresholds carry percentile, window, and method, each linked to the PRD constraint it makes measurable. The 95th percentile is the experience of the slowest one-in-twenty requests.
| Rule / constraint | Consequence here |
|---|---|
| Union assignment-ordering rule[4] | Recommendations are advisory; no assignment completes without dispatcher action (FR-012; automation posture per PRD §10[1]) |
| Contractual response windows[5] | Remaining response time is the 20%-weight ranking input (§4) and appears in the reasons |
| Threshold | Value | Window · method | Operationalizes | On breach |
|---|---|---|---|---|
| Recommendation render time | p95 ≤ 2s | 7-day · measured at the board | PRD: "suggestions appear while the intake call is still going"[1] | ERR-01 path per request + alert to E. Sandoval (engineering lead); two consecutive breach-days go to the weekly pilot review. Latency is not itself a PRD guardrail; sustained breach surfaces through the assignment-speed guardrail the PRD governs |
Pass/fail without interpretation. Given/When/Then for flows, checklists for rules; every criterion names its parent statement, and every Then asserts something observable that isn't just the trigger restated.
| Checklist (validation & permissions) | Parent | Verify |
|---|---|---|
| Unknown skill value rejected, offending value named | FR-013 / §6 | test |
| Location staleness beyond five minutes flags the candidate | §6 | test |
| Permission denial logs an auditable event | §2 / ERR-04 | test |
Two conditional sections legitimately omitted (with their rationale rendered, not silently skipped), one active compatibility section, and the owned question list.
§12 Localization omitted: single-locale deployment (English, Canada) per the business case[2]; revisit at the localization initiative. Rationale recorded.
§13 Scheduled & bulk behavior omitted: all behavior in this requirement is interactive; the nightly telemetry summary belongs to the reporting requirement. Rationale recorded.
Compatibility & transition. The legacy assignment screen goes read-only at the October 1, 2026 pilot cutover; assignments attempted there afterwards are rejected (ERR-05). In-flight jobs keep their assignments unchanged. The breaking change, retiring direct assignment, was accepted in the pilot cutover decision, July 10, 2026[7].
| Open question | Owner | Answer by | Blocks |
|---|---|---|---|
| Are override reason codes tenant-configurable or fixed? | A. Reyes (product lead) | Jul 25, 2026 | FR-012 reason-code list only |
Package items travel in the same export bundle; workspace items link into Specira where the governed record lives.