@rubytech/create-realagent-code 0.1.62 → 0.1.64

package/payload/platform/plugins/preval/skills/property-preval/SKILL.md

@@ -1,146 +0,0 @@
----
-name: property-preval
-description: Use when an operator wants a pre-valuation pack to pitch for a UK property listing — a 5-page A4 PDF that combines a market-data report for the postcode with the subject property's own valuation range, full-width sold + asking comparables, and the agent's recent successes as the sales close. Triggers include "preval <address>", "pre-valuation for <address>", "valuation pitch for <address>", "what's <address> worth and pitch us to list it", "pre-appraisal pack for <address>".
----
-
-# Property Preval
-
-A 5-page A4 PDF that pitches the agent for the listing: cover (full-bleed subject hero), subject valuation (sqft × £/sqft band with operator adjustments), market context, full-width comparables (sold + asking stacked), and the agent's recent successes + disclaimer. **Preval is a sales pitch, not just a data sheet** — every page either tells the vendor what the property is worth or what the agent has recently delivered nearby.
-
-## Typography is fixed; only colours and logos come from the agent
-
-Same typographic lock as `property-market-report`:
-
-- **Display** — Cormorant Garamond (italic for headlines, KPI values, prices, addresses)
-- **Body** — Lora
-- **Sans / labels** — Inter (eyebrows, KPI labels, chips, footer meta)
-
-Never substitute the agent's body or display fonts even if their `DESIGN.md` specifies different families. The pack reads as an editorial / luxury document across every brand. The agent's identity comes through the **palette and logo only**.
-
-## Inputs (never invented)
-
-- **`address`** — full UK address ending in a valid postcode (e.g. `9 Phoenix Drive, Bishop's Stortford, CM23 2UJ`). Skill derives the postcode by matching the UK postcode regex on the final token group; stops if no match.
-- **`brand`** — agent design tokens, same shape as property-market-report: `name`, `tagline`, hex tokens `primary` / `primary_dark` / `accent` / `paper` / `paper_banded` / `rule`. Optional `logo_light` / `logo_dark` filesystem paths. Resolved from the agent's `DESIGN.md` (e.g. `/estate-agents/muvin/DESIGN.md`); read the canonical hex values directly, never substitute "close" colours. Only colour tokens are consumed; typography/spacing/radius tokens in the agent's `DESIGN.md` are ignored by design.
-- **`subject`** — paste-in details about the property being valued:
-  - `cover_hero` (filesystem path or URL to a photo of the subject — required for the cover).
-  - Optional `beds`, `type`, `tenure`, `condition` (well / average / needs work).
-  - `adjustments[]` — operator-curated array of `{label, delta_pct}` covering esoteric factors that shift the headline range (e.g. `{"label":"South-facing garden","delta_pct":3}`, `{"label":"Needs full reno","delta_pct":-8}`). Deltas sum linearly into the final range.
-  - `narrative` — one short paragraph the operator writes about the property.
-  - **Floor area is auto-pulled from the EPC register** via `real-agent-epc` (`epc-lookup-by-address`) and surfaced as `sqft_m2` + derived `sqft`. Both are required. If EPC has no record (pre-2008 property never sold or let; Scotland/NI; unmatched), the operator pastes `subject.sqft` directly **before invocation** as a deliberate override. There is no mid-run paste prompt and no benchmark-only render — a null `sqft` aborts the run with `reason=subject-sqft-missing`.
-- **`agent_listings`** — the agent's recent sold / under-offer / live listings to feature on the closing page. Up to 6 entries of `{url, address, price, beds, type, image, status, slug}` where `status ∈ {"Sold","Under offer","For sale"}`. Operator picks the comps that make the strongest pitch; this is *not* the PropertyData sample.
-- **`market_summary`** — `headline` (one display-italic line), `paragraphs[]` (2–3 short paragraphs), `demand_gauge_position` (percentage string like `"62%"`), `price_growth_note`, `demand_note`. The operator drafts or accepts an LLM stub.
-
-## Tools the skill calls
-
-Parallel fan-out keyed on the derived postcode + the subject address:
-
-**PropertyData (12 calls — credit cost 12):**
-1. `property-data-prices` — asking £ distribution + raw asking comps.
-2. `property-data-prices-per-sqf` — asking £/sqft.
-3. `property-data-sold-prices` — Land Registry sold transactions + raw sold comps.
-4. `property-data-sold-prices-per-sqf` — achieved £/sqft (plus 70pc band used for the valuation range).
-5. `property-data-growth` — 7y price series.
-6. `property-data-growth-psf` — 7y £/sqft series.
-7. `property-data-demand` — for-sale, sales/mo, turnover, MoI, DoM, demand rating.
-8. `property-data-demand-rent` — rental-side demand pillar.
-9. `property-data-property-types` — mix (detached / semi / terraced / flat).
-10. `property-data-crime` — area crime rating + breakdown.
-11. `property-data-flood-risk` — area flood risk (full postcode only).
-12. `property-data-council-tax` — band D + per-property bands (full postcode only).
-
-**EPC (1 call — free, rate-limited):**
-
-13. `epc-lookup-by-address(address, postcode)` — subject floor area + energy ratings + lodgement date.
-
-`address-match-uprn` and `planning-applications` are deliberately omitted (CRM hygiene and dev-precedent reports respectively).
-
-## Output
-
-Directory under `~/Documents/Maxy/preval/<postcode-compact>-<YYYY-MM-DD>/` containing:
-
-- `index.html` — single self-contained file.
-- `img/` — copied logos and the subject hero image.
-- `<slug>-<date>.pdf` — exactly **5** A4 pages. Renderer asserts via `pdfinfo` and raises if ≠ 5.
-
-Return the PDF path to the operator.
-
-## Pages
-
-1. **Cover** — full-bleed `subject.cover_hero` with vertical gradient scrim; light logo top-left; eyebrow "`<brand.name>` · Pre-valuation"; address in display-italic; postcode chip; four-up meta strip (Report · Address · Postcode · Generated). Lifted from property-market-report's cover contract.
-2. **Subject valuation** — KPI strip (sqft, beds, EPC rating, type). Centre panel: headline range = `sqft × sold_psf_low–high` (Land Registry 70pc band) with `sqft × asking_psf` shown as a cross-check. Operator `adjustments[]` displayed as a stacked list (label · delta% · running £). Final range pill at the foot. One paragraph of `subject.narrative` under the panel. `sqft` is required — a null value aborts the run, never renders a benchmark-only panel.
-3. **Market context** — KPI cube (avg asking, avg sold, £/sqft, YoY); pill + gauge for demand; 7y growth sparkline (£ solid + £/sqft dashed); summary paragraphs. Same patterns as property-market-report's page 2.
-4. **Comparables (full-width, stacked)** — Nearest sold table (top 6) full-width across the page; Live asking tile grid (top 4) full-width below. Vertically stacked, never side-by-side — corrects the cramped two-column layout in the v1 preval where the asking tiles got pushed to ~40mm columns of italic addresses.
-5. **Recently with `<brand.name>` + sources** — agent's own listings as a clickable tile grid (`<a>` per card, status badge: Sold / Under offer / For sale), then the sources / methodology / accuracy / investment block. Closes with `Real Agent · Generated <date> · <postcode>` in the footer.
-
-## How to execute
-
-1. Match the postcode out of the address (`/[A-Z]{1,2}[0-9][A-Z0-9]?\s?[0-9][A-Z]{2}/i`). Stop if no match.
-2. Run the 13 fan-out tools (12 PropertyData + 1 EPC) in parallel. Every failure is fail-loud — no mid-run paste prompts, no benchmark-only render, no degraded pack on disk:
-   - **PropertyData `key-not-registered`** → abort `reason=property-data-key-not-registered` with the `property-data-key-register` remediation hint.
-   - **PropertyData `http-429`** → back off and retry the single throttled tool **once**. A second `http-429` aborts `reason=property-data-rate-limited`.
-   - **PropertyData `http-5xx` / network failure** → abort `reason=property-data-unavailable`.
-   - **EPC failure of any kind** — `key-not-registered`, `http-404 (no record on file)`, `http-429`, `http-5xx`, network failure, or MCP not configured on the account — aborts the run. The operator's options before re-running are (a) run Task 155 to deploy / register the EPC MCP, or (b) paste `subject.sqft` (plus `subject.sqft_m2`) into the inputs as a deliberate operator override. There is no in-band prompt and no benchmark-only mode.
-3. Compute valuation range:
-   - `sold_psf_low` = `sold-prices-per-sqf` `70pc_range[0]`
-   - `sold_psf_high` = `sold-prices-per-sqf` `70pc_range[1]`
-   - `low = sqft × sold_psf_low`, `mid = sqft × sold_psf`, `high = sqft × sold_psf_high`
-   - Apply `adjustments` linearly: `factor = 1 + Σ delta_pct / 100`. Final range = `[low × factor, high × factor]`, midpoint = `mid × factor`.
-4. Assemble the `inputs.json` shape per `references/template-inputs.schema.json`.
-5. `python3 references/render.py inputs.json`. Renderer fills the template, copies logos + hero into `img/`, drives Chrome `--print-to-pdf`, asserts page count == 5.
-6. Return the PDF path.
-
-## Adjustments — linear vs compound
-
-Deltas sum linearly (`-8 + 3 = -5%`, applied as `× 0.95`). Compound interpretation (`× 0.92 × 1.03`) would give a slightly different number (-5.24%) but the operator presents the figures verbally as a sum, so the displayed maths must match the verbal claim. If a future operator wants compound adjustments, this is a deliberate skill-level rewrite, not a config switch.
-
-## Observability
-
-- `[preval] start address="<addr>" postcode=<pc>` at run start.
-- `[preval] done pdf=<path> pages=<n> ms=<n>` at run end.
-- `[preval] aborted reason=<cause> address="<addr>" postcode=<pc> ms=<n>` on any abort (one line, then exit 2; no `done`).
-- Each fan-out call emits its own `[property-data] tool=<name>` or `[epc] tool=<name>` line in `server.log` (inherited contracts; no new instrumentation here).
-
-## Hard breakpoints
-
-Each row aborts the run with the named cause. No PDF or `index.html` is left on disk. Operator sees a single-line cause + one-line remediation hint, nothing else.
-
-| Forbidden state | `reason=` cause |
-|---|---|
-| EPC MCP not configured / `key-not-registered` / `http-5xx` / network error | `epc-mcp-unavailable` (operator must run Task 155 or paste `subject.sqft` before invocation) |
-| `subject.sqft` null after EPC lookup | `subject-sqft-missing` |
-| `subject.sqft_m2` null | `subject-sqft-m2-missing` |
-| `subject.cover_hero` missing, unreachable, below 1200×800, or symlinked into another property's folder | `subject-cover-hero-missing` / `subject-cover-hero-unreadable` / `subject-cover-hero-too-small` / `subject-cover-hero-symlinked-foreign` |
-| `brand` not resolved from an on-disk `DESIGN.md` (required token missing) | `brand-unresolved` |
-| `agent_listings` empty | `agent-listings-empty` |
-| `market_summary.paragraphs` < 2 entries | `market-summary-too-thin` |
-| PropertyData any-call `http-429` after 1 retry | `property-data-rate-limited` |
-| PropertyData any-call `key-not-registered` | `property-data-key-not-registered` (operator runs `property-data-key-register`) |
-| EPC lookup returns `http-404` (no record on file) | `epc-no-record` (operator pastes `subject.sqft` as override and re-runs, or accepts that this address can't be preval'd until lodged) |
-
-## Forbidden behaviours
-
-The skill is the contract; if any of these slip through, the pack must not render:
-
-- Silent fallback selection — switching to a benchmark-only / "Estimate requires floor area" panel when an input is missing.
-- Inventing inputs — fabricating `brand`, `subject.cover_hero`, `market_summary.paragraphs`, `agent_listings`, or any field the operator did not supply.
-- Reusing a hero photo from a different property as a placeholder.
-- Defaulting `agent_listings[].status` to `"For sale"` when the source is null.
-- Mid-run prompts for a paste-in (EPC retries, sqft, etc). Overrides are operator-supplied **before** invocation.
-- Omitting the `[preval]` start / done / aborted log emissions.
-- Leaving partial output (`index.html`, `<stem>.pdf`) on disk after an abort.
-
-## Failure diagnostics
-
-- `pages=6` (or ≠ 5) in the `done` line → template overflow on one page. Diagnose with `pdftoppm -png -f <n> -l <n> <pdf>`, then trim that panel's padding only.
-- `start` with no matching `done` or `aborted` within 60s → renderer crashed mid-run. Inspect with `grep -B2 -A20 '\[preval\] start address="<echoed>"' server.log`.
-- `[preval] aborted reason=<cause>` → look up `<cause>` in the **Hard breakpoints** table for the remediation hint.
-
-## Out of scope
-
-- Multi-address batch preval (CSV in → many PDFs out).
-- Loop CRM auto-publish of the PDF onto a contact's record.
-- Pulling `agent_listings` from Loop CRM automatically — operator paste-in for now; CRM wire-up is a separate task.
-- Caching of MCP responses (13 credits per pack is acceptable).
-- A separate cover letter / pitch letter — the cover page *is* the pitch.
-- Compound adjustments (linear sum is the contract; see above).
-- Subject sqft from sources other than EPC and the operator paste-in fallback (e.g. Loop CRM floor plans, Rightmove sqft scrape) — separate task if pursued.