| 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.
