Property-Report-Skill-Judges

Property Investigator Skill — Orchestrator

This root SKILL.md is the skill’s entry point and the orchestrator. It routes to the domain subagents in agents/ (each is a folder with its own SKILL.md) and coordinates the buyer journey. See Agent Architecture & Buyer Journey. A skill is defined by a SKILL.md at its folder root — the orchestrator’s folder is this top-level skill folder, exactly as each subagent’s SKILL.md sits at its own agents/<name>-advisor/ root.

Purpose

Turn any bundle of property documents (seller disclosures, surveys, inspection reports, receipts, HOA docs, title/appraisal, listing sheets, photos) into a professional, decision-grade Property Investigation Report — covering condition, risks, benefits, comparative value, financials, and a resale outlook.

The skill is incremental: point it at a folder of documents and it produces a report. Drop in more documents later and it regenerates an updated report with a change log, without redoing everything from scratch.

This skill produces analysis for decision support. It is not legal, financial, or professional inspection advice. Every report must tell the buyer to verify material items with the appropriate licensed professional.

---

Trigger Phrases

• Guided journey / first-time buyer: “help me buy a house” / “start buying a home” / “I’m a first-time buyer” / “where do I start” (launches the stage-by-stage journey — see Agent Architecture)
• “analyze this property” / “property investigation” / “investigate this house”
• “create a property report” / “generate a property report”
• “should I buy this property” / “risks of buying”
• “review these property documents” / “review the disclosure / survey”
• “update the property report” / “I added more documents”
• “what’s this home worth” / “compare to nearby / comps”
• “5 year outlook / resale” for a property
• “compare these properties” / “which should I buy” / “best buy” / “rank these homes” / “A vs B”
• “compare loan options” / “compare these mortgage quotes” / “which loan is best” / “best mortgage / rate”
• “review my Loan Estimate(s)” / “are these lender fees fair” / “should I pay points” / “loan report”
• “review my insurance quote” / “compare home insurance” / “which insurer is cheapest” / “homeowners insurance help” / “what should I tell the insurance company” / “insurance call prep”
• “review my inspection report” / “analyze home inspection” / “major and minor inspection issues”
• “estimate inspection repairs” / “inspection negotiation” / “is this a deal breaker” / “should I walk away after inspection”
• “review my contract” / “review the executed contract” / “check my termination notice” / “did I sign the right form” / “is my termination valid” / “will I get my earnest money back” / “what are my contract deadlines”
• “how do I avoid losing money before inspection” / “pre-contract checklist” / “should I even go under contract” / “what to ask the seller first” / “what can you pull online for this house” / “who does what — you vs my agent vs the seller” (launches the Pre-Contract Loss-Avoidance Cockpit + the three-lane AI/Human-agent/Seller action split)

---

Core Design Principles

1. Documents are the source of truth. Never invent facts. Every claim in the report must trace to a document or a cited online source. Mark unknowns as “Not disclosed / verify.”
2. Isolation. Treat each property folder as a separate, confidential engagement. Never read or reference documents from a different property folder.
3. Extraction-first. Many disclosures/surveys/receipts are scanned images. Always fall back to image rendering + visual reading when text extraction is empty.
4. Incremental & idempotent. Track processed documents in a manifest. On re-run, only ingest new/changed files and update the report with a dated change log.
5. Confidence + verification. Flag every high-impact finding with a 🔴/🟡/🟢 severity and an explicit “how to verify” action. Every initial report must also state the entry-facing direction with evidence/confidence and give a direct resale-perspective buy verdict with conditions.
6. No hallucinated URLs. Only cite online sources actually fetched. Neighborhood enrichment is required for an initial property investigation when public web/CAD data is available; other enrichment remains optional.
7. Property data only — never personal dossiers (hard rule). Use only public property/parcel records (appraisal district, recorder, listing sites). Never use people-search / background-check services (e.g., fastbackgroundcheck, TruePeopleSearch, Spokeo, BeenVerified, whitepages-people) or compile personal profiles of residents/owners (age, phone, email, relatives, criminal/court records, employment, social media). Owner name as printed on the public appraisal roll is acceptable as a property attribute; going beyond that is out of scope. If a user asks for resident background data, decline that part and explain why, then continue with the property-focused work.
8. Privacy by default. Minimize collection to facts needed for the current decision. Keep raw documents, extracted text, state, and reports inside the resolved property folder. Never place document text, buyer contact data, loan identifiers, signatures, account numbers, or quote details in logs, telemetry, demos, shared comparison folders, or another property’s context. Redact unnecessary personal fields before any approved external-model call; require explicit user/administrator opt-in for model egress. Local processing is the default when provider approval is unknown.
9. Lifecycle and deletion. Tell the user where artifacts are stored. Preserve source documents only while the engagement needs them; on a deletion request, remove that property’s raw documents, extraction/render cache, journey state, reports, dashboards, and timestamped history together. Do not claim deletion from an external provider; follow that provider’s approved retention controls and disclose the boundary.
10. Responsible AI is a release requirement. Apply all six Microsoft Responsible AI principles:
    • Fairness: base recommendations only on property evidence, cost, value, and documented risk. Never use protected traits, resident profiles, or personal-data proxies to score a property or buyer.
    • Reliability and safety: keep outputs evidence-bounded, schema-validated, reversible, and explicit about uncertainty. Never execute an offer, waive a contingency, select a lender/insurer, or replace a licensed professional. Require safety, grounding, prompt-injection, and fallback evaluation before deployment.
    • Privacy and security: enforce the minimization, isolation, egress, retention, and deletion rules above.
    • Inclusiveness: use plain language, responsive output, accessible structure, and non-color-only severity cues; require WCAG 2.2 AA and assistive-technology validation for production interfaces.
    • Transparency: identify source, confidence, verification action, processing mode, evidence boundary, and known limitation for every material recommendation.
    • Accountability: keep the buyer as decision maker, route regulated conclusions to licensed experts, and require named owners, versioned evaluations, incident response, rollback, and release approval. The production control map and acceptance gates are defined in app/RESPONSIBLE-AI.md.
11. Neighborhoods differ per property — don’t hardcode. The right comp set, appraisal district, portal software, and comp radius are different for every house (see Phase 4.5). Always resolve them from the subject’s own county/subdivision; never assume the last property’s setup applies.
12. HTML is the default report format (user preference). Render every narrative deliverable as a self-contained HTML file from templates/report-template.html (Property Investigation, Loan Comparison, Neighborhood, and multi-property Comparison reports). Keep it dependency-free so it opens/prints anywhere. Markdown is now optional/secondary — only produce a .md copy if the user asks. Interactive dashboards (loan/neighborhood) are still generated as their own HTML in addition to the report.

---

Production AI Contract

The runnable prototype is provider-neutral and local-first. It may use GitHub Models, OpenAI, or Azure OpenAI when explicitly configured, and otherwise uses the deterministic grounded analyzer. Azure OpenAI is the production target, not a claim that one model is universally best. It is selected because model access can share the solution’s Azure identity, private-network, regional, governance, safety, and monitoring boundary and integrate with Azure AI Search, Content Safety, Purview, Key Vault, and managed identity. Keep the provider adapter so candidate model/deployment versions can be evaluated and replaced without rewriting the agent workflow.

Grounding and citation

For production retrieval, store approved property documents and licensed/public records in an engagement-scoped Blob container, extract text/tables/pages, and index only approved chunks in Azure AI Search. Every chunk must carry engagementId, propertyId, documentId, document type, page/record locator, source authority, signed/effective date, jurisdiction, and retrieval timestamp. Every specialist query must:

1. Apply mandatory tenant + engagement + property filters before retrieval.
2. Use hybrid keyword/vector retrieval only over evidence approved for that specialist and purpose.
3. Pass retrieved text plus source metadata to the model; never pass results from another property.
4. Cite the document/page or public-record locator for every material finding.
5. Return unknown / verify when retrieved evidence is insufficient or contradictory.

Source conflicts

Do not apply “newest wins” across unlike sources. Use this authority order and preserve every material discrepancy:

1. Latest fully executed legal document or signed amendment over drafts and earlier versions.
2. Official recorder, assessor, permit, or county record over an aggregator for legal/parcel facts.
3. Licensed specialist report over seller/listing language for the specialist’s condition finding.
4. Closed MLS sale over active asking price or CAD mass-appraisal value for sold-comp evidence.
5. Direct lender/insurer document over an email summary or marketplace estimate for quote terms.

If equally authoritative sources still conflict, retain both values, set the field to disputed/unverified, reduce confidence, explain the decision impact, and name the professional or official source that must resolve it. Never silently average conflicting facts.

Evaluation release gate

Evaluate each model, prompt, retrieval configuration, and specialist against versioned, de-identified golden property packets. Record extraction exact-match/F1 for critical fields; citation precision and material-claim coverage; groundedness/unsupported-claim rate; conflict-resolution and abstention accuracy; schema and calculation validity; decision consistency; cross-property leakage; prompt-injection resistance; and licensed expert agreement on high-impact findings. Release thresholds and accountable owners must be approved before customer deployment; failed gates block promotion. See app/RESPONSIBLE-AI.md.

---

Agent Architecture & Buyer Journey

This skill is an orchestrator over five domain subagents in agents/. Each subagent runs independently (by its own trigger phrases) or is invoked by the orchestrator at the right stage of a purchase. Full design: docs/AGENT-ARCHITECTURE-DESIGN.md. User-facing walkthrough of every agent’s inputs/outputs: docs/How-To-Use-Guide.html. Per-agent index: agents/README.md.

Subagent	Folder	Leads stage	Independent triggers (examples)
Neighborhood Advisor	agents/neighborhood-advisor/	Neighborhood & value	“comps”, “what’s this home worth”, “neighbors’ details”
Comparison Advisor	agents/comparison-advisor/	Choosing among homes	“which should I buy”, “best buy”, “A vs B”
Loan Advisor	agents/loan-advisor/	Financing	“compare loans”, “review my Loan Estimate”, “should I pay points”
Inspection Advisor	agents/inspection-advisor/	Option period	“review my inspection”, “estimate repairs”, “should I walk away”
Insurance Advisor	agents/insurance-advisor/	Insurance (pre-closing)	“compare home insurance”, “insurance call prep”

Routing: match the request to a subagent by trigger phrase first. If a property journey is active and the request is ambiguous, pick the stage-appropriate subagent. The orchestrator itself owns Discovery, Investigation, the main report, the contract & deadlines, and closing/move-in.

Why specialists instead of one general agent: each domain has different evidence, calculations, schemas, guardrails, and professional escalation paths. Specialists keep prompts focused, activate only when their inputs exist, can run and be evaluated independently, and limit the blast radius of a prompt/model change. They are logical skill modules, not a claim that six unconstrained model calls always run in parallel.

Coordination loop: route -> retrieve property-scoped evidence -> run specialist -> validate structured result -> update only the owned state section -> reconcile dependent values -> present one next action.

GitHub Copilot invocation. The orchestrator and the five advisors are packaged as discoverable Copilot custom agents in .github/agents/ (property-investigator.agent.md plus one *-advisor.agent.md per specialist), with a slash-command entry point in .github/prompts/property-report.prompt.md. Each advisor agent is thin: it reads its canonical agents/<name>-advisor/SKILL.md (the source of truth) and produces that advisor’s reports. The orchestrator’s agents: list restricts delegation to exactly those five named advisors.

Report-run manifest (proof that “all reports” were produced). At the end of every run the orchestrator writes .property/report-run.json (schema: templates/report-run-schema.json) accounting for every deliverable as created, updated, unchanged, not_applicable, or blocked (with a reason). Never claim all reports were created when a conditional report lacked its inputs — report it as blocked/not applicable instead.

Buyer journey (checklist with dependencies, not a rigid wizard): 0 Readiness → 1 Discovery → 2 Investigation → 3 Neighborhood & value → 4 Financing → 5 Offer & contract → 6 Option period (inspection) → 7 Insurance → 8 Closing prep → 9 Post-closing.

First-time-buyer entry point. Triggers like “help me buy a house”, “start buying a home”, “I’m a first-time buyer”, “where do I start” launch the guided journey. For a first-timer, do the following before diving into documents:

• Explain the journey map above in plain language and where you are in it; set expectations for each stage.
• Stage 0 Readiness: help frame budget and get pre-approved first (invoke Loan Advisor in pre-approval mode — affordability, estimated PITI, cash-to-close, and what documents lenders want) so the buyer shops in range. Explain earnest money, option fee, down payment, and closing costs as distinct.
• Clarify the team they’ll need (buyer’s agent, lender, inspector, insurer, title) and that this tool is decision support, not a replacement for them.
• Then proceed stage-by-stage, invoking each subagent when its inputs exist, and always stating the next step.

Shared journey state — .property/journey.json

One per property; the “spine” every subagent reads for context and writes its results back to. It never contains another property’s data (Principle 2). The authoritative, validated schema is templates/journey-state-schema.json — populate/validate against it. Shape:

{
  "property": { "address": "…", "slug": "…", "reportPrefix": "…",
                "purchasePrice": 0, "loanAmount": null, "replacementCost": null, "county": "…" },
  "stage": "option-period",
  "firstTimeBuyer": false,
  "contract": { "effectiveDate": null, "optionDeadline": null, "financingApprovalDate": null,
                "closingDate": null, "maxRate": null, "financingType": null,
                "asIs": true, "status": "verified|unverified" },
  "value": { "ran": false, "estimatedValue": null, "estimatedValueBasis": null, "cushion": null },
  "loan": { "ran": false, "bestLender": null, "rate": null, "monthlyPITI": null,
            "escrowMonthly": null, "cashToClose": null, "maxRateFlag": null },
  "insurance": { "ran": false, "carrier": null, "annualPremium": null,
                 "roofSettlement": null, "deductibles": null },
  "inspection": { "ran": false, "exposureBase": null, "sellerScope": null,
                  "buyerCredit": null, "priceReduction": null, "dealBreaker": "no|conditional|yes|pending" },
  "openRisks": [],
  "updated": "ISO-8601",
  "versions": []
}

Rules: every write is timestamped and appends a versions entry; a subagent only writes its own section + openRisks; the orchestrator is the sole writer of stage and contract; missing values stay null (never invented).

Cross-agent reconciliation (auto-refresh)

The domains are financially coupled — after any subagent changes numbers, reconcile automatically and keep a new timestamped version (do not silently discard the prior one):

1. Insurance → Loan. When insurance.annualPremium changes and loan.ran = true, auto-refresh the loan escrow, PITI, and cash-to-close, regenerate the loan report/dashboard, and archive the prior HTML to loan/history/ with a yyyy-MM-dd_HHmm stamp. Tell the user to give the lender the final premium.
2. Inspection → Loan / Closing. When inspection.buyerCredit (seller credit) or a price reduction changes, auto-refresh cash-to-close (credits are lender-capped; a price cut changes the loan amount) and re-flag the best pick, archiving the prior version.
3. Contract deadlines → everyone. Option deadline, financing-approval, and closing come from the executed contract; the orchestrator owns them and subagents read but never invent them. A vendor/quote delay never silently extends a deadline.
4. Value cushion ↔ Inspection. Compare repair exposure to the cushion, but a favorable price never cures a safety/structural/insurability defect (kept as separate concepts).

---

Folder Convention

Top-level layout of the skill repo:

Property-Report-Skill/
  SKILL.md                         # ORCHESTRATOR + skill entry point (routing, journey, reconciliation)
  README.md                        # repo overview & quick start
  agents/                          # domain SUBAGENTS (independently triggerable; invoked by the orchestrator)
    README.md                      #   index of the orchestrator + 5 advisors
    neighborhood-advisor/SKILL.md  #   comps / appraisal-district value
    comparison-advisor/SKILL.md    #   multi-property best-buy pick
    loan-advisor/SKILL.md          #   loan/mortgage comparison + pre-approval
    inspection-advisor/SKILL.md    #   inspection exposure + repair budget
    insurance-advisor/SKILL.md     #   insurance call-prep + comparison
  templates/                       # report/dashboard scaffolds + data schemas
  scripts/                         # extractor + helper scripts (extract_documents.py, process_narration.py)
  docs/                            # design & user docs (AGENT-ARCHITECTURE-DESIGN.md, How-To-Use-Guide.html)
  demo/                            # standalone interactive HTML demos (cockpit + mobile app)
  assets/                          # cover art, video, and presentation/ (deck source + built PPTX)
  app/                             # runnable reference web app
  properties/                      # local-only property workspaces plus best-buy comparisons

All properties live under the skill’s properties/ directory, one folder per property (named after the address, e.g. 123-Example-St-Sample-City-ST). Recommended per-property layout (auto-created if missing):

Property-Report-Skill/
  properties/
    <Address-Slug>/
      documents/                     # raw inputs (PDF/DOCX/JPG/PNG). User drops files here.
      data/                          # structured outputs (CSV/JSON) for reuse & year-over-year diffs
      loan/                          # OPTIONAL loan-shopping workspace (Phase 9)
        <Lender Name>/               #   one subfolder per lender; drop that lender's quote PDFs here (e.g. First Lending/, Chase/)
        data/loan-quotes.json        #   normalized quotes (one record per lender+rate option)
        history/                     #   timestamped prior HTML report versions
        Loan-Comparison-Report.html  #   the deliverable (HTML by default — Phase 9)
        loan-comparison-dashboard.html  #   interactive side-by-side (from template)
      insurance/                     # OPTIONAL home-insurance workspace (Phase 10)
        <Company Name>/              #   one subfolder per carrier; drop that carrier's quote PDF(s) here
        Insurance-Call-Prep.html     #   Q&A sheet (from insurance-call-prep-template.html)
        Insurance-Comparison-Report.html  #   data-driven cross-carrier dashboard (from insurance-comparison-dashboard-template.html, when ≥2 quotes)
      inspection/                    # OPTIONAL inspection workspace (Phase 11)
        documents/                   #   inspection reports/photos; user drops files here
        estimates/                   #   specialist evaluations + contractor quotes
        report-page-images/          #   rendered report pages (page-NN.jpg) for per-finding evidence
        data/inspection-findings.json # normalized findings, estimates, and decision record
        data/inspection-evidence.js  #   per-finding inspector text + page image (from template)
        data/diy-guidance.js         #   DIY steps, direct guides, material kits (from template)
        Inspection-Readiness-Checklist.html # pre-inspection preparation
        Inspection-Analysis-Report.html # major/minor findings, cost ranges, negotiation, decision
        Inspection-Repair-Budget.html # interactive budget tool: DIY/specialist plans, filters, evidence, shopping-list export
        Inspection-Repair-Request.html # agent-ready prioritized request; generated only after analysis
        history/                     # timestamped prior HTML versions
      .property/
        manifest.json                # tracked docs: name, hash, type, processed date, key facts
        journey.json                 # shared journey state spine (stage, contract dates, loan/insurance/inspection results)
        extracted/                   # per-document extracted text (cache)
        render/                      # rendered PNGs of scanned pages
      Property-Investigation-Report.html  # the main deliverable (HTML by default — Phase 6)
      Neighborhood-Comparison-Report.html # appraisal-district comp report (Phase 4.5; required on online first run)
      neighborhood-dashboard.html         # interactive comp dashboard (Phase 4.5; required on online first run)

Report file naming (required, all properties). Prefix every generated report/dashboard HTML filename with a short property name — the subdivision/community name from the legal description (e.g. Lakewood-Hills-West-), or a distinctive house name if the user gives one — not the full street address. So the deliverables become e.g. Lakewood-Hills-West-Property-Investigation-Report.html, Lakewood-Hills-West-Neighborhood-Comparison-Report.html, Lakewood-Hills-West-neighborhood-dashboard.html (and the loan/insurance/inspection reports likewise). Keep the data/ CSV/JSON and .property/ files unprefixed. When you prefix or rename, update every internal link and the manifest.json outputs so nothing breaks.

Name the property folder from the address (e.g. 123-Example-St-Sample-City-ST). If the user’s documents are loose in the property folder (not in documents/), treat the whole folder as the document source — do not force a move unless asked.

---

Workflow

Phase 0 — Scope & Isolation

1. Identify the target property folder from the user’s context (open file, mentioned path, or ask).
2. Confirm you will only use documents inside that folder + optional public web data. Do not cross folders.

Phase 1 — Document Discovery & Manifest

1. List every candidate document (.pdf .docx .doc .jpg .jpeg .png .txt .md .xlsx).
2. Load .property/manifest.json if present. Compute a hash (or size+mtime) per file.
3. Determine the delta: NEW files, CHANGED files, and UNCHANGED (skip re-extract, reuse cache).
4. If manifest is missing, treat everything as NEW (first run).

Phase 2 — Extraction (with scanned-image fallback)

For each NEW/CHANGED file, run the extractor (see scripts/extract_documents.py):

• PDF → try text layer (pdfplumber). If a page yields little/no text, render it to PNG (PyMuPDF) and read it visually with the image-viewing tool. Never skip a scanned page.
• DOCX → paragraphs + tables (python-docx).
• Images → view directly.
• XLSX → read sheets.
• Cache results to .property/extracted/<file>.txt and record key facts in the manifest.

Classify each document into a type: seller_disclosure | disclosure_update | survey | title_affidavit | inspection | roof/repair_receipt | hoa | appraisal | listing_sheet | photos | permit | other.

Phase 3 — Structured Data Model

Populate a normalized record (see templates/property-data-schema.json). Capture at least:

• Identity: address, legal (subdivision/block/lot), county, APN, builder (if known).
• Physical: type, stories, sqft, beds/baths, garage, lot size, year built, roof age/type, HVAC, water/sewer, pool.
• Condition/Disclosures: every Yes/aware item, defects, prior repairs, updates (roof, foundation, flooding), termite/WDI, environmental.
• Legal/Encumbrance: easements, encroachments, HOA (dues/mandatory), liens, lawsuits, deaths, permits.
• Flood/Environmental: FEMA zone, flood claims, soil type.
• Financial: list price, price/sqft, taxes, exemptions, HOA fees, utilities/providers.
• Transaction context: seller occupancy/vacancy, motivation signals, offer instructions.
• Provenance: which document each fact came from.

When two documents conflict (e.g., an original disclosure vs. an update), the most recent signed/dated document wins; note the discrepancy explicitly.

Phase 4 — Market Enrichment (web)

If online access is available, enrich (and cite) with:

• Current/most-recent listing (price, DOM, price history, MLS).
• Nearby active competition on Zillow and/or another fetched listing portal: search the same street and immediate neighborhood, record address/ask/basic facts/proximity, and say when no other same-street listing is found. Treat active asks as competition signals, never as sold comps.
• Comps and neighborhood/ZIP median price & $/sqft.
• Builder / original community (new-home listing, archives).
• Market condition (buyer/seller, months of supply) and a multi-year outlook with tailwinds/headwinds. Always label online data with its source and date. If offline, skip and note “market data not enriched.”

Phase 4.5 — Neighborhood & Comparable-Parcel Capture — delegated

→ Delegate to the Neighborhood Advisor subagent (agents/neighborhood-advisor/SKILL.md) automatically during every initial property investigation when public web/CAD access is available. Also delegate whenever the user explicitly wants comps / neighborhood value / “the neighbors’ details,” or during the journey’s value stage. Before the initial investigation is complete, the advisor must write Neighborhood-Comparison-Report.html, neighborhood-dashboard.html, and reusable CSV/JSON in data/; update journey.json.value and the manifest; and return a concise summary for the main report with links to the neighborhood files. If closed MLS sales are unavailable, label the result a CAD mass-appraisal benchmark, not a closed-comp appraisal or sale-value estimate.

Skip this automatic delegation only when the user explicitly opts out or online/CAD data is unavailable or blocked. In that case, the main report and manifest must say that neighborhood outputs were not generated, give the reason, and retain neighborhood value as an open item. Property-only (Principle 7).

Report analyses (orchestrator — used in the main report, Phase 6). Produce these, each with severity + verification actions:

1. Concerns & Risks — 🔴 high / 🟡 moderate / 🟢 low, each with a “verify by” action.
2. Benefits & Strengths.
3. Comparative Value — subject $/sqft vs. comps and ZIP median; explain any gap (size effect, condition, updates, lot, motivation, market). Distinguish statistical discount from real discount.
4. Neighborhood Comparison (if the Neighborhood Advisor ran) — subject vs. same-street/subdivision parcels: county market value, $/sqft, median/average/range; where the subject sits and why. Include the front-door facing direction for every listed parcel/comp (derived from parcel geometry; medium confidence, confirm on-site). Link the data files + dashboard.
5. Financials — price, $/sqft, tax reset caveat, HOA, est. monthly, buyer-cost items.
6. Resale Buy Decision & Multi-year Outlook (mandatory) — answer “Is this worth buying from a resale perspective?” with one direct verdict: yes, conditional yes, or no; state the intended holding period, resale-demand drivers, marketability risks, nearby active competition, and the price/fact/condition that would change the verdict. Use closed comps when available; clearly separate active asking prices, CAD values, and forecasts from sold evidence. Do not hide behind a generic outlook.
7. Due-Diligence Checklist — the exact professional verifications to complete before removing contingencies.
8. Open Items / Unknowns — anything not disclosed that must be confirmed.
9. Investigator’s Bottom Line — overall risk rating + the 1–3 items that decide the deal.
10. Entry Direction & Indian Vastu (mandatory) — determine the entry-facing direction for every initial property report, cite the evidence used, provide an approximate azimuth/one of the 8 directions, and assign high, medium, or low confidence. Give a respectful traditional Vastu read of that facing. If the direction cannot be established, say unverified and make survey/compass verification a prominent open item; never guess. Framing (required): state clearly that Vastu Shastra is a traditional/cultural belief system, not science or an appraisal input, must not override the practical/financial findings, and that a room-level reading needs a Vastu consultant on-site with a compass (reference resource: subhavaastu.com). See the facing-determination method in Tooling Notes.
11. Builder & Build Quality (reusable section) — identify the builder of the subject home and give a reputation rating of 🟢 Highly Recommended, 🟡 Medium / with caution, or 🔴 Low / not recommended.
    • Find the builder from the CAD card, MLS “Builder” field, the community/subdivision developer (e.g. NewHomeSource/TexasNewHomeRebates community pages), the original build-era listing remarks, or the city building permit. If it can’t be tied to this home, mark it UNCONFIRMED — verify and set the rating to PENDING; never guess a builder, and never rate a builder you haven’t confirmed.
    • Rate from real, cited online reviews (Google, Yelp, BBB rating/accreditation + unresolved-complaint pattern, ProsGrade/Birdeye, litigation): 🟢 ≈4.2+/5 with strong BBB and few unresolved complaints; 🟡 ≈3.0–4.1 with recurring service/warranty (non-structural) themes; 🔴 below ≈3.0 or unresolved structural/warranty complaints or active litigation. Always show the sources + dates, note the rating is company-level, not house-specific, and that it never replaces this home’s own inspection. Include the rating-scale legend in the report so it’s self-explanatory.

Phase 5 — Contract, Deadlines & Termination Review (orchestrator-owned)

The orchestrator owns the executed contract and every deadline that flows from it. Run this whenever the user shares a purchase contract/addendum, asks about deadlines, or drops a signed form to validate (e.g. a TREC Notice of Buyer’s Termination of Contract, amendment, or addendum). This is decision-support issue-spotting, not legal advice — always tell the buyer to confirm timing and delivery with their agent/attorney.

1. Establish the source of truth. Use only the latest fully executed contract in the property folder (recency wins; a draft or superseded DigiSign envelope never controls). If no signed version exists, say so and stop — do not validate a termination against an unsigned draft.
2. Capture the controlling terms into journey.json.contract (orchestrator is the sole writer): Effective Date, option-period days + the exact expiration date & time (5:00 p.m. local time rule), financing/ Buyer-Approval deadline, closing date, as-is/repair terms, earnest-money & option-fee amounts and whether/when each was actually delivered, escrow agent, and the full names of all buyers and sellers. Missing/conflicting values stay null and set contract.status = unverified (make that the first 🔴).
3. Extract flattened e-sign PDFs correctly. DigiSign/SkySlope/DocuSign exports are usually flattened — the text layer will not reveal which checkbox is ticked or whether a signature block is filled. Render each page to an image and read it visually (see Tooling Notes). A “DigiSign Verified” header watermark is not proof the signature blocks were completed.
4. Validate a signed form against the contract (checklist):
   • Right form for the goal (e.g. TREC 38-8 / TXR 1902 for a buyer termination) and correct property address.
   • Correct basis selected — the ticked paragraph/box matches the buyer’s actual reason and that right is currently available (option period still open; financing denial with lender’s written statement; appraisal addendum with appraisal attached; POA/HOA, Seller’s Disclosure, or cure-period window, etc.).
   • All required signatures + dates present in the actual signature blocks — for every required party (both co-buyers / co-sellers as named on the contract), not just one.
   • All parties named on the form (e.g. both sellers), matching the executed contract exactly.
   • Timing — compare today’s date to the applicable deadline and the 5:00 p.m. local-time cutoff; state clearly whether it is inside or past the window.
   • Preconditions met — e.g. option fee paid on time (else the unrestricted right is lost under Para. 5D); required lender letter or appraisal attached for a financing/appraisal termination.
   • Delivery, not just signing — the contract’s notice provision requires the notice to be delivered to the other party by the deadline; instruct the buyer to send it per that method through their agent and keep dated proof of delivery. Signing alone does not terminate.
   • Earnest-money outcome — state what the selected basis produces (e.g. option-period termination refunds earnest money, forfeits the option fee) and that release is still governed by the contract.
5. Report the result as a short 🔴/🟡/🟢 validation: what’s correct, what must be fixed before it’s valid, and the exact next action + deadline. Never assert the buyer “can terminate” unless the right traces to the executed contract/addenda and every precondition and deadline is met — flag the rest for the agent/attorney. Warn that termination is irreversible once delivered.

Phase 6 — Report Generation

Render Property-Investigation-Report.html from templates/report-template.html (HTML is the default output — Principle 9). Requirements:

• Fill the header (eyebrow, title, one-line summary, date, overall-risk badge) and put the sections in <main id="content">.
• Snapshot table at top; provenance where useful; severity via <span class="sev r|y|g"> chips; verification actions; key cautions in .callout boxes.
• Keep it self-contained (inline CSS, no external assets) so it opens/prints anywhere.
• Always include the disclaimer. Produce a .md copy only if the user asks.

Phase 7 — Incremental Update Mode (the “add more docs” path)

When re-run after new documents are added:

1. Re-run Phases 1–2 for the delta only.
2. Merge new facts into the data model (recency wins on conflicts; log the change).
3. Re-run the analysis and regenerate the report in place.
4. Prepend/append a dated Change Log section describing:
   • Documents added/changed.
   • Facts that changed and any severity/rating changes (e.g., “Foundation risk downgraded 🔴→🟢 after engineer report added”).
   • New open items resolved or created.
5. Update manifest.json with the newly processed files.

If purchase price or user-provided context changes (e.g., “I’m buying at $X”), treat that as an input and refresh Comparative Value, Financials, and Outlook.

Phase 8 — Multi-Property Comparison & Best-Buy — delegated

→ Delegate to the Comparison Advisor subagent (agents/comparison-advisor/SKILL.md) when the user asks to compare properties / pick the best buy / rank homes. It normalizes each property from its own folder (read-only, no cross-mixing), scores on weighted resale-tilted criteria, and writes one best-buy pick + switch condition to a properties/<A>-vs-<B>-Best-Buy-YYYY-MM-DD.html file in the parent properties/ folder (outside every individual property folder).

Phase 9 — Loan Options Comparison — delegated

→ Delegate to the Loan Advisor subagent (agents/loan-advisor/SKILL.md) when the user wants to compare loan/mortgage quotes or get pre-approved. It extracts each lender’s quote, anchors to the contract’s max rate / closing date, produces Loan-Comparison-Report.html + the interactive loan-comparison-dashboard.html, and records loan.* in journey.json. Financial estimate analysis, not advice. Orchestrator note: after insurance/inspection change numbers, the loan is auto-refreshed (see Cross-agent reconciliation).

Phase 10 — Home Insurance Review & Comparison — delegated

→ Delegate to the Insurance Advisor subagent (agents/insurance-advisor/SKILL.md) when the user shares an insurance quote or asks about insuring the home. It maintains Insurance-Call-Prep.html, builds the data-driven Insurance-Comparison-Report.html for ≥2 carriers, and records insurance.annualPremium etc. in journey.json. Orchestrator note: a new premium triggers the loan escrow auto-refresh.

Phase 11 — Inspection Review, Repair Exposure & Negotiation — delegated

→ Delegate to the Inspection Advisor subagent (agents/inspection-advisor/SKILL.md) when the user adds an inspection report, specialist report, photos, or contractor estimates. It locks the executed-contract option deadline, classifies findings by consequence, and always generates the interactive Inspection-Repair-Budget.html whenever an inspection report is present (this is mandatory, never skipped, never gated on the user asking) plus Inspection-Analysis-Report.html / Inspection-Repair-Request.html, recording inspection.* (including any buyerCredit) in journey.json. Orchestrator note: a seller credit / price change triggers the loan cash-to-close auto-refresh.

---

Tooling Notes

• Extraction script: scripts/extract_documents.py (pdfplumber + python-docx + PyMuPDF render fallback). Install on demand: pip install pdfplumber python-docx PyMuPDF openpyxl.
• For scanned pages with no OCR available, render to PNG at ~170 DPI and read the image visually — do not guess contents.
• Flattened e-sign forms (Phase 5 contract/termination review): for DigiSign/SkySlope/DocuSign exports, the text layer usually omits checkbox marks and signature strokes. Render the page to a PNG at ~200+ DPI (PyMuPDF get_pixmap(matrix=fitz.Matrix(3,3))) and, if needed, crop the signature band and zoom, then read it visually to confirm which box is ticked and whether each signature/date block is actually completed. Do not treat a “Verified” header watermark as a completed signature. Clean up the temporary render afterward unless asked to keep it.
• Clean up any temporary rendered images/scripts after reading unless the user wants them retained.
• Neighborhood capture (Playwright loop pattern) — with the CAD detail page open in the shared browser, loop PropIDs in batches (~7):

  for (const pid of ids) {
    await page.goto(`${DETAIL_BASE}/${pid}/${year}`, {waitUntil:'networkidle'});
    for (const name of ['Values','Improvement'])
      try { await page.locator(`button:has-text("${name}")`).first().click({timeout:2500}); } catch(e){}
    const rec = await page.evaluate(() => { /* scrape address, legal, owner, Main Area sqft, Year Built, 2026 Net Appraised */ });
    out.push({pid, ...rec});
  }
  

  Adapt selectors/labels to the specific CAD portal. Set a generous timeoutMs and batch to avoid timeouts.

• Dashboard: copy templates/neighborhood-dashboard-template.html, replace the DATA array + subject/price constants, keep the privacy footer.
• Loan comparison (Phase 9): copy templates/loan-comparison-dashboard-template.html, set the CONFIG block (price, planned loan, contract maxRate, closing date, holding years) + the QUOTES array (one object per lender), keep the disclaimer footer. The page auto-derives PITI, points break-even, net holding-period cost, and the contract-max-rate / lock-expiry flags. For amounts a quote doesn’t state, use null (renders “—”) rather than guessing. Loan-quote figures are lender estimates — never present them as locked or as financial advice.
• Insurance comparison (Phase 10): copy templates/insurance-comparison-dashboard-template.html to insurance/Insurance-Comparison-Report.html and fill CONFIG + the CARRIERS array + the HOME_ROWS/AUTO_ROWS/GAP_ROWS/SOURCES arrays (table columns and card totals are generated from the data, so 2+ carriers and home-only or home+auto both render, with tier/billing toggles and an editable unknown-fee input). Copy templates/insurance-call-prep-template.html to insurance/Insurance-Call-Prep.html and fill its ``. Use only document-traceable premiums; rebuild fresh each run; dwelling = replacement cost, not price; flag roof RCV vs ACV. Insurance figures are quotes — not insurance or financial advice.
• Inspection repair budget (Phase 11): copy templates/inspection-repair-budget-template.html to inspection/Inspection-Repair-Budget.html, and its two data companions templates/inspection-evidence-template.js → inspection/data/inspection-evidence.js and templates/diy-guidance-template.js → inspection/data/diy-guidance.js. Fill the `` in the HTML header and the DATA arrays (ORIGINAL_ITEMS, HANDLING_BY_ITEM, MINIMUM_BUDGET_COSTS, SPECIALIST_BY_ITEM, TIMING_BY_ITEM, INSURANCE_GROUPS, SPECIALIST_BUNDLES, BUNDLE_CATEGORY_LABELS); render each cited report page to inspection/report-page-images/page-NN.jpg. The engine (filters, presets, evidence expanders, DIY guides, retailer links, CSV + shopping-list export) is property-agnostic — only tokens and data change. Keep DIY only for homeowner-safe work with a stop condition; route roof/structural/gas/energized-electrical/garage-spring/concealed-leak/pressure/HVAC-control/high-access work to a specialist.
• Entry-facing direction (for Vastu / orientation): determine it per property —
  1. Best source: the recorded survey plat. Take a side lot line whose on-page direction (front→back) is unambiguous, read its bearing, convert to azimuth, and the front line’s outward normal (toward the street) = the facing. (Front normal = side-line azimuth ± 90°, choosing the value pointing to the street.) Cross-check with the second side line and the plat’s north arrow.
  2. Fallback: Google/Bing Maps satellite — note the compass direction from the front door out to the street. Report the facing as one of the 8 directions (N/NE/E/SE/S/SW/W/NW) with the approximate azimuth and a confidence level. Then map the 8 Vastu zones onto the floor plan (front = facing direction; back = opposite; sides accordingly).
     • Per-parcel facing for comps (Phase 4.5): apply the same geometry method to every neighborhood comp — for each parcel polygon, take the longest edge (the side lot line / depth axis) and orient it toward the street (resolve the sign using the opposite-row parcels or the road centerline). Snap to the 8-point direction and record the azimuth. Show a Facing column in the neighborhood dashboard/CSV. Medium confidence; note on-site compass verification.
• FEMA flood zone (pull it, don’t defer awareness): query the FEMA National Flood Hazard Layer by point — https://hazards.fema.gov/arcgis/rest/services/public/NFHL/MapServer/28/query?geometry=<lon>,<lat>&geometryType=esriGeometryPoint&inSR=4326&spatialRel=esriSpatialRelIntersects&outFields=FLD_ZONE,SFHA_TF&returnGeometry=false&f=json (fetch same-origin from a hazards.fema.gov page — direct file-origin fetch is CORS-blocked; the msc.fema.gov search page only renders the zone in an interactive map). FLD_ZONE=X with SFHA_TF=F = not in a Special Flood Hazard Area (no mandated flood insurance). State the zone as awareness; the binding determination is still the lender’s (a human-lane task). Get each property’s lat/long from the listing/map link.
• Pre-Contract Loss-Avoidance Cockpit (Stage 0–1 buyer tool, reusable/property-agnostic): a self-contained interactive HTML saved in the parent properties/ folder (not a property subfolder), properties/Pre-Contract-Loss-Avoidance-Checklist.html. Purpose: minimize sunk loss (option fee + inspection) by gating money against deal-killers knowable for $0 from the seller’s disclosure + MLS history + public records before going under contract. Tabs: 🚦 Go/No-Go (3-state red-line gates → any Fail = NO-GO, Unknown = CAUTION, all pass = GO; editable money-at-risk meter of sunk vs refundable), 👥 Who Does What (three lanes, below), 🔗 Verify Online (address-aware link launcher: CAD by county, FEMA, USDA soil, permits, Zillow/Redfin, Street View, GreatSchools). localStorage persistence. Two rules to teach every buyer: “Free before fee” (clear the free gates before spending) and “Credit ≠ cure” (for roof/structural/insurability, require replace/repair by a licensed pro + warranty + reinspection, never a cash credit that leaves the buyer owning the defect). This workflow prevents buyers from paying option and inspection costs before reviewing material conditions already disclosed or available in public records.
• Three-lane responsibility split — “agent” = the AI agent (me), NOT a human realtor. Whenever you split who-does-what, use three non-overlapping lanes (a per-property …Action-Split.html in the property folder, and the cockpit’s “Who Does What” tab): 🤖 AI agent (me) = everything obtainable from public data (CAD value/legal/sqft/history/owner-of-record, public listing price/DOM/relist history, school ratings, entry facing/Vastu, builder ID + review rating, neighborhood CAD comps, source-conflict detection, public permit-portal search, FEMA flood-zone query); 🧑‍💼 Human agent / licensed pros = ONLY licensed/physical/transactional work I cannot do (full MLS private remarks + CMA + closed comps, order the HOA resale certificate, order a new survey, lender flood determination, official tax certificate + title commitment, bind insurance, schedule/attend inspection + property access, draft/submit offer & deliver TREC notices); 🗝️ Seller = condition truth (disclosure §5.008, replace-vs-credit posture FIRST, roof invoice/warranty/transfer, foundation records, prior inspections, CLUE claims, permits, survey+T-47, builder name). Never place an AI-doable item in the human lane. Actually fetch the AI-lane items; do not merely promise them.

Quality Bar (self-check before delivering)

• Every material claim traces to a document or cited source.
• Conflicts between documents resolved by recency and flagged.
• Scanned/image documents were actually read, not skipped.
• Each risk has a severity and a verification action.
• Disclaimer present; no legal/financial advice framing.
• Manifest updated so the next run is incremental.
• No documents from other properties were referenced.
• (Initial online investigation) Neighborhood report, dashboard, and CSV/JSON were generated and linked from the main report; journey.json.value and the manifest were updated. If skipped, the report and manifest state the permitted reason.
• (Every initial report) Entry-facing direction/Vastu section includes evidence, direction/azimuth, confidence, cultural-not-scientific framing, and an on-site verification action; unknown is never guessed.
• (Every initial report) Resale section gives a direct yes/conditional-yes/no verdict, intended holding period, demand drivers, risks, nearby active competition, and a clear condition that changes the verdict.
• (If Phase 5) Validation used the latest executed contract; deadlines/terms captured to journey.json.contract (or marked unverified); flattened e-sign pages were rendered and read visually (checkbox + every signature/date block confirmed, not inferred from a “Verified” watermark); the selected basis, party names, timing/5 p.m. cutoff, preconditions (e.g. option fee paid), and delivery were all checked; earnest-money outcome stated; no termination right asserted unless it traces to the contract and is agent/attorney-confirmable.
• Neighborhood/comp set resolved from THIS property’s county & subdivision (not copied from a prior run).
• Only public property data used — no people-search / resident background data.
• (If Phase 9) Every loan quote traced to a provided document; missing figures marked “verify,” not invented; quotes checked against the contract max rate & closing/lock dates; loan disclaimer present (not financial advice).
• (If Phase 11) Executed-contract deadline was verified or prominently marked unverified; every finding has page/section provenance; scanned pages/photos and report limitations were reviewed.
• (If Phase 11) Major/minor classification is consequence-based; estimates are low/base/high and labeled quote vs allowance; root causes are not double-counted.
• (If Phase 11) The recommendation has explicit proceed, negotiate/extend, and walk-away triggers; credit/repair terms are flagged for agent/lender/title confirmation.
• (If Phase 11) Inspection-Repair-Budget.html exists — it is MANDATORY whenever an inspection report is present (never skipped, never gated on the user asking); it was generated from the template with its two data files; every finding maps to one handling method, one specialist type, and one bundle; each DIY-eligible row has a stop condition, material kit, and retailer links; page images render; and there is no mobile overflow.

Anti-Patterns (do NOT)

• Do not fabricate facts, comps, URLs, or figures.
• Do not skip a scanned page because text extraction returned empty.
• Do not mix data across different property folders.
• Do not present asking price as market value, or a single forecast number as certainty.
• Do not use background-check / people-search sites or compile personal profiles of owners/residents.
• Do not assume the appraisal district, portal URL shape, or comp definition from a previous property — re-resolve per house.
• Do not invent loan rates/fees or present a quote as a locked rate or a lending commitment; loan figures are lender estimates and this is not financial advice.
• Do not treat an inspection-summary checkbox, item count, repair-cost percentage, or planning allowance as proof of a defect, a contractor quote, or an automatic right to terminate.