/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`, `bil