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