Vertical Home Services

---
name: vertical-home-services
description: Domain-knowledge pack for home & field services (HVAC, plumbing, cleaning, landscaping) — the trades vocabulary, non-obvious pricing/dispatch rules, and field-crew realities a builder must know so home-services products aren't speced naive. Covers the four products this niche ships (dispatch, quoting, field-booking, reviews), how they wedge against ServiceTitan / Jobber / Housecall Pro, and the must-model entities (price book, membership, job window, multi-option quote). Applied by architect/pm during spec authoring so the schema and flows reflect how a trades shop actually runs, not a generic CRUD app.
when_to_use: |
  Apply when architect/pm specs a home-services product:
  - architect writes ARCH-*.md for a dispatch / quoting / field-booking / reviews product in the home-services niche
  - pm decomposes any of those four products into tasks and needs the domain rules to not under-scope
  - design-advisor wireframes a tech-facing or homeowner-facing flow for a trades shop
  Do NOT apply for non-field verticals (the entity model here assumes crews, trucks, and on-site jobs).
effort: low
allowed-tools: Read, Write, Grep, Glob
paths:
  - "docs/architecture/**"
  - "docs/plans/**"
  - "docs/design/**"
---

# Home & field services — spec it like a trades shop runs

HVAC, plumbing, cleaning, landscaping. A crew of techs in trucks, jobs on
site, money quoted at the kitchen table. A builder who models this as
"appointments + invoices" ships something no contractor will use. This
skill is the domain briefing so the spec is right before code starts.

## 1. Domain vocabulary (know these or look naive)

- **Price book** — the master catalog of priced tasks ("replace 40-gal
  water heater = $1,850"). Pricing is *looked up*, not computed hourly.
- **Flat-rate vs T&M** — flat-rate (one price from the price book, parts +
  labor bundled) is the norm in the trades. Time & materials (T&M, billed
  by the hour + parts) is the exception, used for diagnostics or open-ended
  jobs. Build for flat-rate first.
- **Dispatch board** — the live grid of techs × time slots the office uses
  to assign and re-shuffle jobs through the day.
- **Truck roll** — sending a tech to a site. Every truck roll has a real
  cost; minimizing wasted rolls is the whole game.
- **First-time fix rate** — % of jobs completed on the first visit. The
  north-star ops metric. Low fix rate = repeat rolls = lost margin.
- **Callback** — a return visit because the first fix failed. Tracked and
  hated; ties to warranty.
- **Membership / service agreement** — recurring plan (e.g. 2 tune-ups/yr
  for $19/mo) that creates predictable revenue and priority booking. A core
  business model, not a loyalty gimmick.
- **Good-better-best** — the quote presents 3 priced options (e.g. patch /
  replace / replace-with-upgrade). Standard sales technique; lifts ticket.
- **Dispatch fee / trip charge** — flat fee just to show up, often waived
  if the job is booked.
- **After-hours / emergency rate** — premium pricing for nights, weekends,
  holidays. Same price book, different multiplier.
- **GPS / route** — tech locations and optimized drive order; drives the
  "tech is 12 min away" customer text.
- **Parts markup** — parts billed above cost (often 2–3×); a margin lever,
  must be representable per line.

## 2. Non-obvious domain rules (what makes this vertical specific)

- **Pricing is a lookup, not arithmetic.** The price comes off the price
  book at a flat rate. Hourly math is the rare path, not the default.
- **The quote IS the sales tool.** It's presented on site, often on a
  tablet, and closed on the spot — interactive, branded, good-better-best,
  accept-and-pay. It is not a PDF emailed for later.
- **Techs work offline.** Basements, mechanical rooms, rural sites — no
  signal. The field app must capture work, photos, and signatures offline
  and sync later. This is a hard requirement, not a nice-to-have.
- **Same-day dispatch is normal.** Jobs get created, assigned, and
  re-shuffled within the same day; the board is a live, mutable thing.
- **Demand is seasonal and spiky.** HVAC floods on the first heat wave /
  cold snap; landscaping is spring-loaded. Capacity and booking must absorb
  surge, not assume even flow.
- **Appointments are windows, not instants.** Customers get "8am–12pm",
  not "8:00". Model an arrival window plus narrowing ("tech en route").
- **Recurring is first-class.** Memberships, maintenance plans, seasonal
  visits — the schema has to express recurrence and renewal natively.

## 3. What a naive build gets wrong

- ❌ **Hourly pricing.** Modeling jobs as hours × rate. The trades quote
  flat-rate off a price book; hourly is the edge case. Get this wrong and
  the product is unsellable.
- ❌ **No offline mode.** Assuming the tech has signal. The most common
  job site is a basement. An online-only field app fails on day one.
- ❌ **Quote as static PDF.** A read-only document instead of an
  interactive accept-to-pay surface with selectable options and a deposit
  button. The quote must *close the sale*, not describe it.
- ❌ **No good-better-best.** A single price with no upsell tiers. Leaves
  margin on the table and feels foreign to anyone who's bought HVAC.
- ❌ **No membership / recurring model.** Treating every job as one-off.
  Misses the predictable-revenue engine the whole business runs on.
- ❌ **Instant appointments.** Booking a 9:00 slot when the trade works in
  windows. Sets a customer expectation the crew can't meet.

## 4. Must-model entities / fields (beyond generic CRUD)

Schema hints — keep these migration-friendly (see [[migration-ready-schema]]):

- **PriceBookItem** — `code`, `name`, `category`, `flat_rate`, `cost`,
  `parts_markup`, and tier prices `{good, better, best}`; `is_recurring`
  flag for membership-eligible items. T&M items carry an hourly rate as
  the exception path.
- **Membership / ServiceAgreement** — `plan`, `cadence` (e.g. 2/yr),
  `price`, `billing_interval`, `renewal_date`, `priority_flag`, linked
  customer; generates scheduled visits.
- **Job** — `status` (scheduled → dispatched → en_route → on_site →
  complete → callback), `assigned_tech`, `arrival_window {start,end}`,
  `address`, `is_after_hours`, `first_time_fix` flag, parent membership if
  recurring.
- **Quote** — array of `options[]` (good/better/best), each with line
  items off the price book; `selected_option`, `deposit_amount`,
  `deposit_paid`, `accepted_at`, branding; an accept action that converts
  to a Job.
- **Tech / Crew** — skills/licenses held, home base, working hours,
  current GPS, capacity.

## 5. Per-product notes (wedge + the one thing to get right)

- **dispatch** (crud) — assign jobs to techs, optimize routes, live status
  board. *Wedge:* ServiceTitan is ~$300+/tech and enterprise-heavy; the
  wedge is a clean same-day board a 3–8 truck shop can actually run without
  an implementation consultant. *Must get right:* the board is **live and
  mutable** — jobs re-assign and re-window mid-day, with arrival windows
  (not instants) and tech status driving the customer "on the way" text.
- **quoting** (marketplace-lite) — photo/form → priced branded quote →
  accept + pay deposit. *Wedge:* vs Jobber/Housecall, lean into the
  **interactive accept-to-pay** quote that closes on site. *Must get
  right:* good-better-best options priced off the **price book**, with a
  deposit step — the quote is the sales tool, not a PDF.
- **field-booking** (booking) — customer self-books a slot, gets
  reminders/confirmations. *Wedge:* incumbents bury self-booking; expose a
  dead-simple homeowner booking page. *Must get right:* book into an
  **arrival window** against real crew capacity, then drive reminders and
  confirmations (consent + timing deferred to [[lifecycle-messaging]]).
- **reviews** (crm) — request/route/publish reviews after each job.
  *Wedge:* automate the post-job review ask that shops do by hand.
  *Must get right:* fire the request **on job completion** (tied to the
  first-time-fix outcome, not a blind blast), route happy → public
  platforms, unhappy → private recovery; SMS/email mechanics via
  [[lifecycle-messaging]].

## 6. Compliance / regulatory touchpoints (light — pointers, not full treatments)

- **Trade licensing & permits** — HVAC/plumbing/electrical work is
  licensed and often permit-pulled per jurisdiction. Don't model trade
  qualification; *do* let a Job/Tech carry a license/permit reference field
  so a regulated build can extend it.
- **TCPA (SMS reminders)** — booking confirmations/reminders are SMS;
  consent, STOP/HELP, and quiet hours apply. Defer all messaging infra and
  consent design to [[lifecycle-messaging]] — just flag that reminders
  exist so it's speced in, not bolted on.
- **Deposits / payments** — quotes take a deposit and jobs collect
  payment. Defer PCI scope, idempotency, and refund/dispute flow to the
  billing/payments layer — the spec only needs the `deposit_amount` /
  `deposit_paid` fields, not the processor design.

## Output

When applied, the architect/pm carries these into ARCH-*.md / PLAN-*.md:
the price-book-flat-rate pricing model, the offline field requirement, the
window-based scheduling, the multi-option accept-to-pay quote, and the
membership/recurring entity — and cross-references [[lifecycle-messaging]],
[[migration-ready-schema]], and [[vertical-onboarding]] rather than
re-deriving them.