vertical-real-estate git:20260622.9c16feaA

Immutable. This exact content is served forever at /api/v1/blob/5eb4f9abedf3ee0d.

---
name: vertical-real-estate
description: Residential-proptech domain knowledge so architect / pm aren't naive when speccing real-estate products (listings, lead-crm, transaction-coordination, property-mgmt). Codifies MLS/IDX reality, listing status lifecycle + syndication canonical-source, long-cycle lead nurture, transaction-coordination as the high-pain wedge, and the must-model entities. Applied during spec authoring so the architecture reflects how real estate actually works — not a generic CRUD assumption.
when_to_use: |
  Apply when architect or pm is speccing a residential real-estate / proptech product:
  - listings (content) — build once, syndicate to every portal
  - lead-crm (crm) — capture + long-cycle automated nurture
  - transaction-coordination (crud) — tasks / docs / deadlines to close
  - property-mgmt (crud) — rent, maintenance, tenant comms
  Use to seed the domain model + the "what a naive build gets wrong" checklist before tasks are decomposed.
effort: low
allowed-tools: Read, Write, Grep, Glob
paths:
  - "docs/architecture/**"
  - "docs/plans/**"
  - "docs/design/**"
---

# Vertical: residential real estate — don't spec it naively

Real estate looks like generic CRUD (a listing is a record, a lead is a contact, a deal is
a checklist). It isn't. The domain has hard-won structure — MLS quirks, status lifecycles,
months-long sales cycles, agent-vs-brokerage data boundaries — that a naive build ignores
and then rebuilds. This skill front-loads that structure so the spec is right the first time.

Incumbents to know (and what they own): **Lone Wolf / Propertybase** (brokerage CRM + back
office), **Follow Up Boss** (lead-to-close CRM, the nurture gold standard), **CINC** (lead-gen
+ CRM), **Top Producer** (legacy CRM), **kvCORE / BoldTrail** (all-in-one platform). They are
expensive, broad, and switching-cost-heavy — which is why the wedge matters (see per-product).

## 1. Domain vocabulary (use these terms in the spec)

- **MLS** (Multiple Listing Service) — regional database of listings; there are ~500+ MLSs in
  the US, each its own system, login, and field set. There is no single national MLS.
- **IDX** (Internet Data Exchange) — the rules + feed that let a brokerage display *other*
  brokers' MLS listings on its own site. Governed by per-MLS display/redistribution rules.
- **RESO** — the standards body. **RESO Web API** (modern REST/OData feed) and **RESO Data
  Dictionary** (canonical field names) are the standard — but adoption and cleanliness vary
  per MLS. "RESO-compliant" still means per-MLS quirks.
- **Listing status** — lifecycle, not a flag: `active → pending / contingent → closed`
  (plus `coming soon`, `active under contract`, `withdrawn`, `expired`, `sold`). Status
  drives display rules and downstream automation.
- **Buyer agent vs seller (listing) agent** — opposite sides of a transaction; data and
  permissions differ. A contact can be a buyer lead and later a seller.
- **Brokerage vs agent** — the brokerage holds the license and (often) the data; the agent is
  the user. Commission **split** is how the deal's commission divides brokerage↔agent.
- **Escrow / settlement / closing** — the funded close; **contingencies** (inspection,
  financing, appraisal) are conditions that must clear first, each with a **deadline**.
- **Transaction coordinator (TC)** — the person who shepherds a deal from accepted-offer to
  close: chasing docs, signatures, and deadlines. Often done in Dotloop / Excel today.
- **CMA** (Comparative Market Analysis) — comp-based price estimate an agent gives a seller.
- **Lead-to-close funnel** — capture → nurture → active → under-contract → closed; months long.
- **Syndication portals** — **Zillow, Realtor.com**, Redfin, Trulia, etc.; a listing is
  pushed (syndicated) to many; our copy is one of many downstream copies.

## 2. Non-obvious domain rules (the stuff that breaks naive specs)

- **There is no one MLS schema.** Each MLS has its own auth, field quirks, photo handling, and
  redistribution rules. RESO standardizes the *intent* but the data is messy per-MLS. Model an
  **integration adapter per MLS**, not one global importer.
- **Transaction-coordination is the underserved, high-pain wedge.** It's the part still done in
  Dotloop/Excel with manual deadline-chasing. Low switching cost (it's not the system of record
  for leads), high pain, clear ROI. Lead this if choosing where to land first.
- **A listing has a canonical source and many syndicated copies.** The MLS record (or our
  record) is the source of truth; portal copies derive from it. Don't model portal copies as
  independent listings — model `source` + `syndication targets`.
- **Lead nurture is long-cycle.** A real-estate lead can sit warm for **6–18 months**. The CRM's
  job is *not* close-this-week; it's stay-top-of-mind for months with automated drip until the
  lead is ready. A short-funnel CRM design is simply wrong for this domain.

## 3. What a naive build gets wrong

- ❌ **One MLS schema.** Assuming a single import format. Reality: per-MLS adapter, per-MLS
  redistribution rules, RESO Data Dictionary as the *target* normalization, not the source.
- ❌ **Listing without status lifecycle + syndication canonical.** A flat "listing" row with no
  status state machine and no source/target model can't drive display rules or feed portals.
- ❌ **TC checklist without deadline + contingency tracking.** A plain task list misses the
  point: the value is enforced **deadlines** and **contingency** clearing, with alerts.
- ❌ **Lead CRM without long-cycle nurture.** Stage + next-touch + multi-month drip is the core;
  a pipeline-only CRM (close/lost in weeks) doesn't fit.
- ❌ **Ignoring agent-vs-brokerage data boundaries.** Who owns the lead and listing data —
  agent or brokerage — is a real permission/ownership boundary. Bake it into the model, not
  bolt it on later.

## 4. Must-model entities

Seed the domain model with these (exact fields negotiable; the *shape* is not):

- **Listing** — `status` (lifecycle state machine, §1), `source_ref` (MLS id / RESO key — the
  canonical source), `syndication_targets[]` (Zillow/Realtor.com/… with per-target state),
  price, address, beds/baths, floorSize, photos, listing_agent, brokerage.
- **Lead** — `stage` (capture→nurture→active→under-contract→closed), `last_contact_at`, owning
  agent, source, buyer/seller intent, and an attached **long-cycle nurture** (drip campaign,
  next-touch date). Tie to [[lifecycle-messaging]].
- **Transaction** — `checklist[]` (tasks), `deadlines[]` (each dated + owner + alert),
  `contingencies[]` (inspection/financing/appraisal, each with clear-by date + status),
  `documents[]` (e-signed), parties (buyer/seller/agents/TC), close date.
- **Property / Unit** + **MaintenanceRequest** (status, priority, tenant, assignee, photos),
  Lease/rent (amount, due date, tenant), tenant-comms thread. (property-mgmt.)

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

- **listings** (content) — *the one thing*: **MLS/IDX correctness** — per-MLS adapter,
  `source_ref` canonical, status lifecycle, redistribution-compliant display. Pairs with
  [[local-seo]] (listings must rank + syndicate; our page is the canonical, portal copies
  point back) and [[migration-ready-schema]] (`source_ref` = MLS/RESO key for re-import/dedupe).
- **lead-crm** (crm) — *the one thing*: **long-cycle nurture** — months-long automated drip,
  stage + last-contact, top-of-mind not close-now. Competes with Follow Up Boss; the bar is
  nurture quality. Pairs with [[lifecycle-messaging]].
- **transaction-coordination** (crud) — *the one thing*: this **IS the wedge** — low switching
  cost, high pain, replaces Dotloop/Excel. Get **deadline + contingency tracking** right (dated,
  owned, alerted); the checklist alone is table stakes. Recommend landing here first.
- **property-mgmt** (crud) — *the one thing*: **maintenance-request + rent + tenant-comms** as
  first-class flows; don't reduce it to a generic ticket list. Don't hold tenant/owner funds
  naively (see §6 escrow/trust).

## 6. Compliance (light — flag for the reviewer, don't solve here)

- **MLS / IDX redistribution + display rules** — per-MLS; controls what may be displayed, for
  how long, with what attribution. The integration adapter must honor them.
- **Fair Housing Act** — listing/ad copy and targeting must not discriminate (protected
  classes). Applies to listing descriptions and any lead-targeting automation.
- **Escrow / trust-account basics** — do **not** hold or move client/tenant funds naively.
  Earnest money and rent flow through trust/escrow with strict accounting; integrate a
  compliant provider rather than building a wallet.
- **E-sign** — transaction docs need legally-valid e-signature (ESIGN/UETA); use a real e-sign
  provider, capture audit trail.

## Output

When applied, contribute a **Domain model** block to the architecture/design doc:

```
## Domain model (real estate)
- entities: Listing(status lifecycle + source_ref + syndication_targets) · Lead(stage + last_contact + nurture) · Transaction(checklist + deadlines + contingencies + docs) · Property/Unit + MaintenanceRequest
- wedge: <which product lands first + why> (default: transaction-coordination)
- MLS/IDX: per-MLS adapter · RESO Data Dictionary as normalization target · redistribution rules honored
- nurture: long-cycle (6–18mo) drip, not short funnel
- compliance flags: IDX display rules · Fair Housing (copy) · escrow/trust (no naive funds) · e-sign
```