diff --git a/docs/property-assessor.md b/docs/property-assessor.md index 133dd6d..fb1fb14 100644 --- a/docs/property-assessor.md +++ b/docs/property-assessor.md @@ -1,84 +1,326 @@ # property-assessor -Decision-grade residential property assessment with required photo review, comp checks, carry-cost underwriting, and explicit buy/pass guidance. +Decision-grade residential property assessment skill for OpenClaw. -## What this skill is for +This skill is for evaluating a condo, townhouse, house, or similar residential property from an address or listing URL and ending with a practical recommendation such as `buy`, `pass`, or `only below X`. -- Assessing a property from an address, Zillow URL, HAR URL, or other listing source -- Reconciling baseline facts across multiple listing/public sources -- Reviewing listing photos before making condition claims -- Producing a practical verdict such as `buy`, `pass`, or `only below X` +## Overview + +`property-assessor` is a workflow skill, not just a scraper. It is meant to: + +- normalize the target property across listing sources +- build a baseline fact set +- review listing photos before making condition claims +- compare the property against nearby or same-building comps +- underwrite taxes, HOA, insurance, and realistic carrying costs +- identify risk drivers +- produce a concise but decision-grade verdict + +The skill is designed for real-world purchase decisions, especially when you need a fast read on whether a property is worth pursuing. + +## Accepted inputs + +The skill can start from any of: + +- a street address +- a Zillow listing URL +- a HAR listing URL +- an address plus user constraints such as: + - investment only + - owner-occupant + - long-term rental + - short-term rental + - target distance/location requirements + +Preferred starting point is the address when available, because it makes source reconciliation easier. ## Core workflow +Default operating sequence: + 1. Normalize the address and property type. -2. Build a baseline fact set from the best available listing or record source. -3. Cross-check facts on other sources. -4. Review photos before making condition claims. -5. Pull comps. -6. Underwrite carry costs and risk factors. -7. End with a clear verdict and fair-value guidance. +2. Discover accessible listing and public-record sources for the same property. +3. Establish a baseline fact set from the best available source. +4. Cross-check the same property on other sources. +5. Review listing photos before making condition claims. +6. Pull same-building comps for condos or nearby comps for houses/townhomes. +7. Underwrite carry costs and risk drivers. +8. End with a specific recommendation and fair-value range. -## Required photo-review workflow +## Source priority -Photo review is mandatory when a listing source exposes photos. +Unless the user asks otherwise, preferred source order is: -Preferred source order: 1. Zillow -2. HAR +2. Redfin 3. Realtor.com -4. Brokerage mirror or other accessible listing mirror +4. HAR / Homes.com / brokerage mirrors +5. county or appraisal pages -Rules: -- Do not claim condition from structured text alone when listing photos are available. -- Prefer accessible all-photos views, photo grids, or scrollable photo pages over fragile next-arrow traversal. -- If the primary source fails but a fallback source exposes the photos, continue with the fallback. -- If photo review is incomplete, say so explicitly and lower confidence. +Use high-quality mirrors to confirm facts, not to override a clearly better primary listing without reason. + +## Minimum data to capture + +For the target property, capture as many of these as the sources support: + +- address +- list price or last known list price +- property type +- beds / baths +- square footage +- lot size if relevant +- year built +- HOA fee and included services +- taxes +- days on market +- price history +- parking +- waterfront / flood clues +- subdivision or building name +- same-building or nearby active inventory +- listing photos and visible condition cues +- included appliances and obvious missing appliances +- flooring mix, especially carpet + +## Photo-review requirement + +Photo review is mandatory when the listing sources expose photos. + +Do not make strong condition claims from structured text alone if photos are available. + +### What counts as acceptable photo access + +Preferred photo sources are: + +- a scrollable all-photos page +- an expanded photo grid +- a photo page that exposes the full set +- a modal/lightbox only if the site does not provide a better all-photos path + +Do not treat these as full photo review by themselves: + +- the listing hero image +- a collage preview +- a photo count without image access +- listing shell text that mentions photos + +### What to inspect in the photos + +At minimum, evaluate: + +- overall finish level: dated, average, lightly updated, fully updated +- kitchen condition: cabinets, counters, backsplash, appliances +- bathroom condition: vanity, tile, surrounds, fixtures +- flooring: tile, vinyl, laminate, hardwood, carpet +- obvious make-ready issues: paint, trim, wear, damage, mismatched finishes +- visible missing items: refrigerator, washer/dryer, range hood, dishwasher +- signs of deferred maintenance or water intrusion +- exterior and common-area condition where visible +- waterfront-facing elements, balconies, decks, sliders, and windows when relevant + +### If photo review is incomplete + +If the agent cannot access enough photos to make a credible read: + +- say so explicitly +- lower confidence +- avoid strong turnkey claims +- continue the broader underwriting work, but mark condition as limited-confidence ## Zillow and HAR integration -This skill now expects the dedicated `web-automation` extractors first. +This skill now expects the dedicated `web-automation` extractors first instead of fragile ad hoc gallery automation. -### Zillow +### Zillow first + +Run: ```bash cd ~/.openclaw/workspace/skills/web-automation/scripts node zillow-photos.js "" ``` -Success means: -- the Zillow all-photos page opened, or -- Zillow's rendered listing shell already exposed the full direct image set and the extracted count matches the announced count +Successful Zillow photo access means one of these happened: -The returned `imageUrls` are the photo-review set. Review those images before making condition claims. +- the `See all photos` / `See all X photos` path opened a usable all-photos experience, or +- the rendered Zillow listing shell already exposed the full direct Zillow image set and the extracted count matches the announced count + +Important rule: +- when the extractor returns `imageUrls`, that returned set is the photo-review set + +For smaller listings, review the full extracted set when practical. For a 20-30 photo listing, that usually means all photos. ### HAR fallback +If Zillow does not expose a reliable image set, use HAR next: + ```bash cd ~/.openclaw/workspace/skills/web-automation/scripts node har-photos.js "" ``` -Use HAR when Zillow does not expose a reliable photo set. The returned `imageUrls` are the review set for the fallback path. +Successful HAR photo access means: -## Approval-safe command shape +- the HAR listing opened +- `Show all photos` / `View all photos` exposed the photo page +- direct `pics.harstatic.com` image URLs were extracted -For chat-driven runs, prefer file-based commands under `~/.openclaw/workspace/skills/web-automation/scripts`. +As with Zillow, the returned `imageUrls` are the review set for condition analysis. + +### Practical photo-source order + +Use this action order: + +1. Zillow extractor +2. HAR extractor +3. Realtor.com photo page +4. brokerage mirror or other accessible listing mirror + +Do not stop after the first failed source if a fallback source can still expose the photos. + +## Approval-safe execution + +For chat-driven property assessments, prefer file-based commands under: + +```text +~/.openclaw/workspace/skills/web-automation/scripts +``` + +Good command shape: -Good: - `node check-install.js` - `node zillow-photos.js ""` - `node har-photos.js ""` Avoid when possible: + - `node -e "..."` - `node --input-type=module -e "..."` -## Output requirements +Why this matters: + +- OpenClaw exec approvals are easier to allowlist for stable file paths +- inline interpreter eval is more likely to trigger approval friction +- the installed approval allowlist is typically already scoped to the `*.js` files under the `web-automation/scripts` directory + +## Make-ready normalization + +Condition should be translated into a rough make-ready range so pricing and comp comparisons stay realistic. + +Use simple buckets: + +- light make-ready + - paint, fixtures, minor hardware, small patching +- medium make-ready + - partial flooring replacement, appliance replacement, bathroom refresh +- heavy make-ready + - significant kitchen/bath work, widespread flooring, visible deferred maintenance + +Call out carpet separately when present, especially in bedrooms, stairs, or living areas. + +## Underwriting expectations + +The final assessment should show a simple carrying-cost view including: + +- principal and interest if available +- taxes per month +- HOA per month if applicable +- insurance estimate or explicit uncertainty +- realistic carry range after maintenance, vacancy, and property-specific risk + +Strong caution flags include: + +- high HOA relative to price or expected rent +- older waterfront or coastal exposure +- unknown reserve or assessment history for condos +- many active units in the same building or micro-area +- stale days on market with weak price action +- no clear rent support + +## Output contract + +The final answer should stay concise but decision-grade. + +Recommended structure: + +1. Snapshot +2. What I like +3. What I do not like +4. Comp view +5. Underwriting / carry view +6. Risks and diligence items +7. Verdict with fair-value range and offer guidance + +The output must explicitly include: -The final assessment should explicitly include: - `Photo source attempts: ...` -- `Photo review: completed via ` or `Photo review: not completed` +- `Photo review: completed via ` + or `Photo review: not completed` -If photo review was completed, briefly summarize the condition read from the photos. -If not, mark condition confidence as limited and explain why. +If photo review was completed: + +- summarize the condition read from the photos +- mention obvious finish level, flooring, appliance presence, and make-ready signals + +If not completed: + +- mark condition confidence as limited +- explain why photo access was incomplete + +## Example validation flow + +Use these commands for a known-good regression check. + +### Verify extractor prerequisites + +```bash +cd ~/.openclaw/workspace/skills/web-automation/scripts +node check-install.js +npm run test:photos +``` + +### Zillow regression check + +```bash +cd ~/.openclaw/workspace/skills/web-automation/scripts +node zillow-photos.js "https://www.zillow.com/homedetails/4141-Whiteley-Dr-Corpus-Christi-TX-78418/2103723704_zpid/" +``` + +Expected shape: + +- `complete: true` +- `expectedPhotoCount: 29` +- `photoCount: 29` + +### HAR regression check + +```bash +cd ~/.openclaw/workspace/skills/web-automation/scripts +node har-photos.js "https://www.har.com/homedetail/4141-whiteley-dr-corpus-christi-tx-78418/14069438" +``` + +Expected shape: + +- `complete: true` +- `expectedPhotoCount: 29` +- `photoCount: 29` + +### Skill-level validation + +When testing `property-assessor` itself, confirm the resulting assessment: + +- attempts Zillow first +- falls back to HAR if needed +- references actual photo access, not just listing text +- includes the required `Photo source attempts` line +- includes the required `Photo review` line +- makes condition claims consistent with the reviewed image set + +## Related files + +- installed skill instructions: + - `~/.openclaw/workspace/skills/property-assessor/SKILL.md` +- repo skill instructions: + - `skills/property-assessor/SKILL.md` +- photo extractor docs: + - `docs/web-automation.md`