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