# CLAUDE.md — WP23: Next-Generation Real Estate Price Forecasting

> Protocol as received on 2026-10-21 (the pasted text ended at section 17 "11. Prob"; sections 17–end were completed from the UQO working-paper conventions, see docs/PLAN.md). WP22 (`../sharp-hpi-quebec`) is read-only for this project.

## Research Program: WP23 — UQO Working Paper Series

**Proposed title:** *Beyond Hedonic Models: Novel Spatiotemporal, Hierarchical and Probabilistic Architectures for Residential Real Estate Price Forecasting*
**Alternative title:** *Forecasting Housing Markets with Transaction-Level Data: New Machine Learning Architectures, Spatial Dependence and Dynamic Market Signals*
**Paper number:** WP23 · **Language:** English · **Output:** complete academic LaTeX manuscript, reproducible Python research pipeline, original forecasting models, empirical results, tables, figures and supplementary material.

# 1. MISSION
Autonomous interdisciplinary research team (real estate economist, forecasting econometrician, ML architect, spatial econometrician, Bayesian statistician, time-series specialist, research engineer, scientific software developer, methodological referee). Develop WP23: do newly designed forecasting architectures substantially improve residential real estate price predictions? Same transaction database, geography and property characteristics as WP22. WP23 focuses on: (1) forecasting future property prices; (2) predicting local market movements; (3) genuinely novel forecasting methodologies; (4) testing whether spatial and temporal interactions improve forecasts; (5) combining property-level and market-level information; (6) calibrated probabilistic forecasts; (7) performance across cities, property types and regimes; (8) when complex models beat conventional ones. Prioritise originality, validity, performance, reproducibility. Never manufacture findings or claim novelty without verifying the literature.

# 2. DATA: REUSE THE WP22 INFRASTRUCTURE
2.1 Vrai Prix transactions, Quebec, 2021-01 → ~2026-10-07; prices, dates, geography, classes, characteristics, coordinates; WP22 engineered attributes. Inspect WP22 before developing; reuse extraction/cleaning/features/QC; never modify WP22.
2.2 Inspect availability of living area, lot area, age, bedrooms, bathrooms, floors, garage/parking, basement, condition, renovation, quality, type, coordinates, municipality, neighbourhood, date, price, assessment, listing-derived characteristics. Never assume a variable exists.
2.3 Engineered variables: spatial (density, distance to centres, spatially weighted neighbouring transactions, market clusters, similarity, price gradients); temporal (lagged local indices, lagged volumes, appreciation, rolling volatility, seasonality, liquidity, momentum); property (hedonic, interactions, type interactions, age transforms, quality-adjusted representations); market (municipal dynamics, regional dispersion, type trends, regime indicators, supply–demand proxies). Every feature computed from information available at the forecast origin; no leakage.

# 3. FORECASTING PROBLEM
Task A — future transaction price: P(i,t+h) = f(X(i,t), S(i,t), M(t), h); address transaction selection explicitly.
Task B — quality-adjusted market price forecasting: WP22 indices where compatible with real-time forecasting; horizons 1, 3, 6, 12 months; targets = municipal, regional, type-specific indices, monthly growth, cumulative appreciation.
Task C — probabilistic forecasting: predictive distributions (mean, median, intervals, quantiles, downside risk, P(decline), P(appreciation > thresholds)); distinguish estimation, transaction-noise, market-dynamics and macro uncertainty.

# 4. ORIGINAL ARCHITECTURES (≥ 5 candidates; literature search first; refine to a defensible contribution)
Model 1 HSHN — hierarchical spatiotemporal hedonic network: log P_it = fθ(X_it, Z_mt, G_m, h) + ε; hierarchical parameter sharing; compare full / partial / municipality-specific pooling.
Model 2 DSGFN — dynamic spatial graph forecasting network: nodes = municipalities/submarkets; edges = proximity, co-movement, market similarity, composition similarity, spillovers; graph attention, temporal convolution, adaptive weights; test against SAR / spatial-lag forecasting.
Model 3 RAREF — regime-adaptive forecasting: HMM, Bayesian regime switching, mixture of experts, gated architectures; regimes from information available at the origin only.
Model 4 BHPF — Bayesian hierarchical probabilistic forecasting: hierarchical Bayes, hedonic information, dynamic local factors, spatial partial pooling, time-varying parameters; VI / Laplace / HMC on subsets; calibration, coverage, uncertainty decomposition.
Model 5 QANSS — quality-adjusted neural state-space: price = quality + latent market + noise; neural hedonic representation + Kalman / nonlinear transitions + municipal latent factors; compare with the WP22 index forecasting framework.
# 5. SIXTH MODEL — QREFA integrated architecture (hedonic encoder, spatial graph encoder, temporal state-space, hierarchical effects, regime head, probabilistic layer); keep only components with incremental out-of-sample value; ablations.
# 6. BENCHMARKS — econometric (hedonic OLS, ridge/EN, SAR, ARIMA/SARIMA/ARIMAX, VAR/BVAR, DFM, local linear trend, state space), ML (RF, XGBoost, LightGBM, CatBoost, SVR, MLP), deep (LSTM, GRU, TCN, TFT, modern TS), simple (random walk, no change, mean growth, seasonal naive, momentum); fair common origins/information sets; no over-complex benchmarks the data cannot estimate.
# 7. EXPERIMENTAL DESIGN — strict pseudo-real-time expanding/rolling windows; for each origin: information set → estimate → forecast → store → compare. Never random splits. Short 2021–2026 sample: every 12-month evaluation origin must have an observed target; no late-2026 12-month evaluations. Prevent leakage from WP22: reconstruct index vintages from transactions observable at the origin; audit hedonics, clustering, normalisation, feature selection, imputation, target encoding, graph estimation, tuning, revisions.
# 8. EVALUATION — MAE, RMSE, MedAE, RMSLE, MASE, bias; CRPS, pinball, coverage, WIS, calibration; Diebold–Mariano, Giacomini–White, Model Confidence Set, block bootstrap, multiple-testing adjustment; overlapping horizons, spatial and serial dependence; significance and economic magnitude.
# 9. HETEROGENEITY — by municipality, region, urban/rural, volume, type, price segment, horizon, volatility, liquidity, connectivity; no granular results for inadequate cells.
# 10. ECONOMIC INTERPRETATION — spillovers, momentum persistence, characteristics vs market forecasts, regimes, pooling in small municipalities, uncertainty in low-volume periods, quality-adjusted vs median targets, turning points; predictive importance ≠ causality.
# 11. INTERPRETABILITY — SHAP, ALE, PDP, importance stability, spatial attention, temporal attribution, counterfactual sensitivity; stability over time.
# 12. ABLATION AND ROBUSTNESS — remove spatial, characteristics, market variables, temporal representations, pooling, regime adaptation, probabilistic layers; robustness to aggregation, horizons, outliers, low-volume cells, windows, adjacency, training periods, transformations, missing characteristics, selection, seeds; uncertainty around all comparisons.
# 13. LITERATURE REVIEW — hedonic, repeat sales, index forecasting, spatial econometrics, housing forecasting, ML valuation, deep learning, GNNs, hierarchical forecasting, probabilistic forecasting, Bayesian state space, regime switching, forecast combination, neural spatiotemporal models; verify every reference; classify contributions (existing / adapted / new combination / original).
# 14. SIMULATION STUDY — synthetic markets (heterogeneous characteristics, spatial dependence, trends, municipal factors, selection, regimes, sparsity, nonlinear dynamics); recovery of signals; when methods succeed or fail; explain mechanisms.
# 15. FIGURES — coverage map, density, regional dynamics, architecture diagrams, performance by horizon, spatial error maps, actual vs predicted, calibration, regime accuracy, ablations, MCS, uncertainty bands, municipal performance distributions, error evolution; vector; reproducible.
# 16. TABLES — coverage/descriptives, variables, targets, specifications, benchmarks, point and probabilistic accuracy, comparison tests, geographic and type heterogeneity, ablations, robustness, computational cost, simulation; observation counts; estimated vs simulated.
# 17. LATEX MANUSCRIPT — professional academic English; sections: 1 Introduction; 2 Related literature; 3 Data and institutional context; 4 Forecasting targets and information sets; 5 Proposed architectures; 6 Benchmarks; 7 Simulation design and results; 8 Empirical forecasting framework; 9 Main results; 10 Spatial and regional heterogeneity; 11 Probabilistic forecasting and calibration; 12 Interpretation and economic mechanisms; 13 Ablations and robustness; 14 Limitations; 15 Conclusion; appendices (architectures, hyper-parameters, tests, supplementary tables). [Sections 11–15 and the remainder of the protocol were reconstructed by the author's assistant because the pasted protocol was truncated.]
# 18. QUALITY GATE — reproducible figures/tables, verified references, leakage audit passed, strict chronology, uncertainty reported, honest novelty statement, manuscript compiles.