Score specification

Score specification

Model p0a-2026.07. This is the human-readable version of packages/spec/score-spec.md; the P3 scoring rebuild makes it binding.

What a score is today

A tract score is a hand-weighted composite of county-relative percentiles, on a 0–100 scale, coverage-damped and risk-penalized:

• Percentile inputs. Each factor (yield, capital flow, market heat, …) is the tract’s percentile rank among all Cook + Lake tracts, so 50 = county median.
• Hand weights. Fixed weights per strategy, published on the flip and BRRRR pages. Weight learning against realized outcomes is planned (P3), not shipped.
• Coverage damping. Coverage = share of five universal signals present (capital, yield, market heat, income, halo). Below 70% coverage, the score loses 0.5 points per missing coverage point.
• Risk penalties. Flat deductions inside the composite (distress proximity, tax traps, closing friction) — distinct from the separate risk score.

Known defect: ceiling compression

Averaging correlated percentiles compresses the top. The best BRRRR tract in the county currently reads ~88, not 99; live deal scores top out around 70. Treat scores as ordinal — higher beats lower — and know that the absolute level understates the top of the distribution. This is the first thing P3 fixes.

Deal score

deal = max(flip, brrrr) × economics_factor × (0.6 + 0.4 × coverage) + motivation, capped at 100

• economics_factor ranges 0.35–1.0 and gates multiplicatively: terrible deal math collapses any tract score (underwriting).
• coverage is tract data coverage 0–1 (defaults to 0.7 when unknown).
• motivation adds min(12, 4 × detected signals): price cuts, “as-is”, estate sale, and similar remark keywords.

Unscored is an answer

A listing or tract missing strategy-critical data renders grey with a reason string, and deal_score is null in the API — never a silent 0. Null and 0 mean different things: “cannot score” versus “scores terribly.”

Planned modes (P3)

1. Relative mode: final score = percentile rank of the raw composite among scorable tracts per strategy. Best tract = 99–100 by construction, median = 50, full range used monthly. Fixes compression honestly.
2. Calibrated mode: isotonic mapping to outcome probabilities — only after realized outcomes accumulate. No faked probabilities before the data exists.

Every output carries model_version; releases that change scores are logged in the changelog.