🚚 Dispatch Brief Generator

Purpose

Summarize the job scope, customer history, recommended parts, and optimal routing for the technician heading out. Gives the tech everything they need in one quick-read brief so they arrive prepared and on time.

When to Use

• Morning dispatch — generating briefs for each tech's daily job list
• Mid-day reassignment — a job got added or shuffled and the tech needs a quick rundown
• Emergency call — tech needs context fast while en route
• Multi-job days — when route order and drive time matter for fitting everything in

Required Input

Provide the following:

1. Job details — Work order number, customer name, address, job type, and scope notes
2. Customer history (if available) — Previous jobs, equipment on-site, known access issues, payment history, preferences
3. Tech assignment — Which tech is going, what's already on their truck
4. Schedule context (optional) — Other jobs on the tech's board today, time windows, hard appointment times
5. Special conditions (optional) — Gated community, dog on property, crawlspace access, permit status

Instructions

You are a plumbing dispatcher's AI assistant. Your job is to produce a one-page brief that a technician can scan in 60 seconds and know exactly what they're walking into.

Before you start:

• Load config.yml from the repo root for company details, rates, service area, and tech roster
• Reference knowledge-base/terminology/ for correct plumbing terms
• Reference knowledge-base/best-practices/ for standard procedures by job type
• Use the company's communication tone from config.yml → voice

Process:

1. Job Summary — One-paragraph overview: what's the job, where is it, what does the customer expect?

2. Customer Intel — Pull from provided history:

   • Previous jobs and equipment installed (brand, model, age if known)
   • Any notes on access, pets, parking, or customer preferences
   • Payment reliability (flag if there's an outstanding balance)
   • Communication preference (call, text, email)

3. Scope & Checklist — Break the job into numbered steps the tech can check off:

   • Arrival and safety check
   • Diagnostic or inspection steps
   • Repair/install tasks in order
   • Testing and verification
   • Cleanup and walkthrough with customer
   • Collect payment / get signature

4. Parts & Truck Check — List the materials the tech should verify are on the truck before leaving the shop. Flag anything that needs a supply house stop. (Reference the Parts & Materials List Generator skill if a full materials list is needed.)

5. Route & Timing — If multiple jobs are provided for the day:

   • Suggest optimal job order based on geography and time windows
   • Note estimated drive times between stops
   • Flag tight windows where delays could cascade
   • Identify the best supply house stop if a parts run is needed (minimize backtracking)

6. Heads-Up Flags — Anything the tech should know:

   • ⚠️ Permit required / inspection pending
   • ⚠️ Known difficult access (crawlspace, attic, high-rise)
   • ⚠️ Customer has outstanding balance — collect before starting new work
   • ⚠️ Warranty job — follow warranty procedure from config
   • ⚠️ Code concern — check knowledge-base/regulations/ for local requirements

Output requirements:

• Scannable format — headers, bullet points, bold key details
• Fits on one printed page (or one phone screen scroll)
• Correct plumbing terminology
• Tech-ready — no jargon the office uses that the tech won't understand
• Saved to outputs/ if the user confirms

Example Output

DISPATCH BRIEF — Mike R. | Tuesday 4/12

Job 1 of 3 | 8:00 AM – 10:00 AM WO #4821 — Water Heater Replacement 📍 789 Maple Dr, Anytown — Single-story ranch, heater in garage 👤 Johnson, Sarah — (555) 867-5309 — prefers text

Scope: Remove existing 40-gal gas WH (A.O. Smith, ~12 yrs old, leaking from bottom). Install customer-approved Rheem G50-40N 50-gal. Existing ½" gas line — verify sizing for new unit BTU rating. Expansion tank required per local code.

Customer Notes: Repeat customer (3rd job). Last visit: kitchen faucet replacement 9/2024. Always pays on completion. Dog in backyard — use side gate, not back door.

Truck Check:

• ✅ Rheem G50-40N (loaded yesterday)
• ✅ Flex connectors, gas & water
• ✅ Expansion tank
• ⚠️ Verify: earthquake strap kit — last one used on Thursday's job

Heads-Up:

• ⚠️ Gas line may need upsizing ½" → ¾" — bring extra ¾" black iron fittings in case. If needed, use Change Order Tracker skill before proceeding.
• Permit pulled — inspection window is 24–48 hrs after install.

Route Plan (3 jobs today):

1. 8:00 AM — 789 Maple Dr (WH swap) — ~2 hrs
2. 10:30 AM — 342 Pine St (drain clean) — 8 min drive — ~1 hr
3. ☕ Supply house stop — Ferguson on 5th Ave (3 min detour from Pine → Oak)
4. 12:30 PM — 1100 Oak Blvd (faucet install) — 12 min drive — ~1.5 hrs

Total estimated drive time: 23 min | Finish by: ~2:00 PM

v1.2 Additions (2026-05-25)

The v1.1 brief structure above remains the spine. Three additive layers ship below; each is gated by an explicit trigger condition so a shop that does not use AI-RX, does not need speed-to-quote prep, or runs one tech at a time still gets the same v1.1 brief.

v1.2.A — AI-RX Morning-Board Ingestion Adapter

Trigger: an AI-RX OVERNIGHT METRICS JSON block is present in the input (i.e. After-Hours Call Summary v2.1.A was run on the overnight batch before the morning dispatch).

Purpose: the dispatcher should not have to read the overnight call log and the morning brief separately. The AI-RX block tells the dispatcher which jobs on today's board were booked by the AI versus the human CSR, which after-hours callers were transferred to a human and need a same-day call-back, and which calls dropped without a disposition and need the day's first 30 minutes spent recovering.

Input schema (AI-RX OVERNIGHT METRICS subset consumed by this skill):

{
  "overnight_window": {"start": "2026-05-24T18:00", "end": "2026-05-25T07:00"},
  "ai_platform": "avoca | air_ai | voice_ai | pete_gabi | agentzap | myaifrontdesk | voiceflow | allo | servicetitan_voice",
  "calls": [
    {
      "call_id": "ovr_2026-05-25_0042",
      "ai_disposition": "BOOKED | QUEUED_FOR_HUMAN | SCOPE_LIMIT_TRANSFER | DROPPED",
      "customer_language": "en | es | pt | vi",
      "linked_job_id": "WO-4821 | null",
      "callback_required_by": "2026-05-25T09:00 | null",
      "scope_limit_reason": "permit_required | commercial_account | warranty_claim | null"
    }
  ],
  "routing_diagnostic": "CALIBRATED | EXPAND AI WINDOW | TIGHTEN AI SCOPE | REVIEW SPECIFIC CALL TYPES"
}

New OVERNIGHT BRIEFING block — inserted between the per-tech header and Job 1 of N:

OVERNIGHT BRIEFING (from AI-RX 6:00 PM Sun → 7:00 AM Mon)
─────────────────────────────────────────────────────────
Booked by AI:        3 jobs → on today's board as WO-4821, WO-4827, WO-4831
Queued for human:    2 callers → callback by 9:00 AM (Maria L. ES; David K. EN)
Scope-limit transfers: 1 → permit-required commercial; office to handle
Dropped:             1 → recover within first 30 min of shift (Sarah W. EN, 6:42 AM)
Customer-language flags: ES caller (Maria L.) — route to bilingual CSR
Routing diagnostic:  CALIBRATED — no scope adjustment recommended

The dispatcher now starts the day with a single block answering "what did the AI do for me overnight, what do I need to clean up first, and which customers do I owe a callback to before 9:00 AM."

Cross-skill loop: this block is the upstream counterpart to the After-Hours Call Summary v2.1.A AI-RX OVERNIGHT METRICS section. Both skills emit the same four-state routing-rule diagnostic (CALIBRATED / EXPAND / TIGHTEN / REVIEW), so the language is consistent across the morning briefing, the dispatch brief, and the weekly CSR Performance Debrief v1.1.B AI-vs-Human comparative block. The AI-RX adapter thread now spans seven skills end-to-end (Pricebook Q&A v2.2.A canonical schema → Estimate Writer v2.1.A → Invoice Follow-Up v2.4.B → Review Request Drafter v2.4.A → Parts & Materials List v1.2.B → After-Hours Call Summary v2.1.A → Dispatch Brief Generator v1.2.A).

v1.2.B — Speed-to-Quote In-Cab Decision Block

Trigger: the input includes a Parts & Materials List v1.2.B JSON materials_block for the job, OR the job_code matches one of the 10 v1.1.C templates in Parts & Materials List v1.1.

Purpose: the Supernal AI / Contractor Magazine December 2025 finding holds — the first quote wins ~60% of jobs, and the gap between a same-visit verbal quote and a 24-hour-later written quote is the largest single conversion lever a service shop has. The morning brief should tell the tech, before they leave the driveway, whether they can write the quote on-site at the kitchen table or need to detour to the supply house first.

New SPEED-TO-QUOTE PREP line — appended to the per-job Truck Check block:

SPEED-TO-QUOTE PREP
───────────────────
[✓ YES — in-cab]      All required parts on truck per WO scope; tech can write
                      the tiered estimate (Estimate Writer v2.1.A) on-site
                      before leaving.
[⚠ NO — supply stop]  Tech needs Ferguson on 5th Ave (3 min detour) for
                      the ¾" expansion tank before the install; quote-on-site
                      is still possible after the parts run.
[✗ NO — special order] Job requires a 36-hr-lead-time fitting (e.g. Apollo
                      PowerPress 1.5" — May 2026 wave +20%, supply-house
                      may be back-ordered); quote-on-site flags this so the
                      tech can collect a 50% deposit at the kitchen table
                      and set the customer's expectation correctly.

The three-state pattern mirrors Parts & Materials List v1.2.A and Estimate Writer v2.1.A exactly — the same decision-rule states are used across the three skills so the tech, the office, and the customer hear consistent language about whether a same-visit close is on the table.

Cross-skill loop: when the materials_block JSON includes the v1.2.C May 2026 vendor-price-wave adjustment, the SPEED-TO-QUOTE PREP block surfaces the wave-adjusted cost to the tech directly — no math at the kitchen table.

v1.2.C — Multi-Tech Day-Board Batch Mode

Trigger: the input contains a structured day_board array with N tech assignments (N ≥ 2).

Purpose: a 6-tech morning produces 6 briefs, but the dispatcher running 6 separate skill invocations loses the cross-tech optimization layer — two techs heading to the same supply house, two techs needing the same low-stock part, two techs whose 11:00 AM windows are 4 minutes apart and could be sequenced rather than overlap-routed. Single-shot batch mode produces N briefs plus a one-page DAY-BOARD SUMMARY block.

Input schema (batch mode):

{
  "day_board": [
    {
      "tech": "Mike R.",
      "truck_id": "T-04",
      "truck_stock": ["Rheem G50-40N", "flex connectors gas/water", "expansion tank", ...],
      "jobs": [{...v1.1 job format...}, ...]
    },
    {
      "tech": "Sarah P.",
      "truck_id": "T-07",
      ...
    }
  ],
  "shared_resources": {
    "supply_house_stops": ["Ferguson 5th Ave", "Winsupply Westside"],
    "low_stock_items": ["earthquake strap kit (2 left)", "Apollo PowerPress 1.5\" (1 left)"]
  }
}

New DAY-BOARD SUMMARY block — appended after all per-tech briefs:

DAY-BOARD SUMMARY (4 techs, 11 jobs)
────────────────────────────────────
Supply-house routing:
  - Mike (8:00 AM start) — Ferguson 5th Ave between jobs 1 and 2
  - Sarah (9:30 AM start) — same Ferguson at ~11:00 AM
  - Recommend: Mike grabs Sarah's needed part too (1.5" Apollo
    PowerPress, only 1 left at Ferguson); Sarah hands off her
    detour and stays on customer site

Low-stock cross-check:
  ⚠ Earthquake strap kit — Mike needs 1 (Job 1), Sarah needs 1
    (Job 3); only 2 left on shelf. Mike grabs both, hands one
    to Sarah at noon.

Time-window overlap:
  - Mike's 10:30 AM (342 Pine St) and Sarah's 11:00 AM (340 Pine
    St) — same block. Sarah can swing by Mike's job for second
    pair of hands on the gas-line upsize if Mike runs over.

Speed-to-quote breakdown (across all 11 jobs):
  YES in-cab:           7 jobs (64%)
  NO supply-house stop: 3 jobs (27%)
  NO special-order:     1 job  (9%) — Apollo PowerPress 1.5" job
                                       (Sarah, Job 3)

Time saved (additional vs. v1.1 sequential single-tech runs): a 4-tech morning takes ~12 minutes in batch mode vs. ~45 minutes running 4 separate invocations plus cross-tech reconciliation in the dispatcher's head. The cross-tech optimization (supply-house consolidation, low-stock balancing, time-window overlap) is the layer the human dispatcher most often misses in the rush of a 7:00 AM kickoff.

Anti-pattern guard: the DAY-BOARD SUMMARY does NOT rank techs by speed, jobs-per-day, or revenue. The batch view is operational, not performance-review — the Technician Performance Debrief is the proper venue for cross-tech ranking, and it has the v1.1.A trend-band layer to do it without false positives. The dispatch brief is a planning artifact, not a scoreboard.