Add capital gains distribution planning doc (#818 #817)

[vahid-ahmadi]

Summary

• Model capital gains distribution considering all income groups together #818 asks for a multivariate capital gains imputation instead of the current per-income-decile-independent fits. Avoid imputing capital gains to households with zero wealth #817 reports the related failure mode of imputing gains to zero-wealth households.
• The imputation itself lives in policyengine-uk-data, but persist the model-facing plan in-repo at docs/book/assumptions/capital-gains-distribution-plan.md so the cross-repo agreement is discoverable from one place.
• Page covers:
  • current state — per-decile marginal distributions fit to HMRC CGT statistics by income;
  • three limitations — overfitting at decile boundaries, no wealth conditioning (Avoid imputing capital gains to households with zero wealth #817), no within-decile correlation;
  • two candidate approaches: (A) multivariate Gaussian KDE following the OG-USA bequest-transmission model, (B) a two-stage QRF reusing the existing imputation infrastructure already proposed in the #1621 pipeline-alignment plan;
  • recommendation: B, because the infrastructure exists, QRF handles correlated predictors naturally, and adding total_wealth as a predictor solves both Model capital gains distribution considering all income groups together #818 (overfitting) and Avoid imputing capital gains to households with zero wealth #817 (zero-wealth gains) in one move;
  • model-side surface: negligible — the capital_gains_before_response input stays the same; one new regression test ("no positive gains on zero-wealth households") lives well in policyengine_uk/tests/;
  • open questions on the wealth donor source (FRS vs WAS) and elasticity-by-band as a follow-up.

Closes both #818 and #817 in the planning sense (the data-side implementation is the actual work).

Test plan

• Markdown lints cleanly.
• Docs build job picks up the new page under assumptions/.

🤖 Generated with Claude Code