Skip to content

Add Benefits-in-Kind planning docs page (#1654)#1707

Open
vahid-ahmadi wants to merge 1 commit into
mainfrom
vahid-ahmadi/issue-1654-bik-plan-doc
Open

Add Benefits-in-Kind planning docs page (#1654)#1707
vahid-ahmadi wants to merge 1 commit into
mainfrom
vahid-ahmadi/issue-1654-bik-plan-doc

Conversation

@vahid-ahmadi
Copy link
Copy Markdown
Collaborator

Summary

  • Closes Plan: model benefits-in-kind (BiK) — scope, implementation, and data needs #1654 (the planning tracker).
  • Plan: model benefits-in-kind (BiK) — scope, implementation, and data needs #1654 was filed as a planning issue but lived only in GitHub. Persist the agreed plan in-repo as a "planned: not yet modelled" page at docs/book/programs/gov/hmrc/benefits-in-kind.md so future work has a stable reference rather than a moving issue body.
  • The page covers:
    • Current state — the integration hook in variables/household/benefits/employment_benefits.py is explicitly documented as the slot future BiK variables plug into.
    • Phase 1 MVP scope — company car, car fuel, private medical, living accommodation, beneficial loans.
    • Phases 2 & 3 and the exempt-from-charge out-of-scope set.
    • Implementation plan — proposed variables under variables/gov/hmrc/income_tax/bik/, parameter tree layout, and knock-on effects through ANI / PA taper / HICBC / Class 1A NICs.
    • Data needs — the FRS-flag-but-no-value gap per category, plus calibration sources (HMRC BiK statistics, Company Car Tax statistics, SPI tables, DVLA/SMMT).
    • Imputation approach mirroring the second-stage-imputation pattern from Align UK model/data pipeline with US patterns: reported-anchoring, second-stage imputation, and downstream bugs #1621.
    • Effort estimate and open questions (Class 1A NICs, UC treatment, Datalab access).
  • When the MVP lands, the "planned" warning at the top is dropped and the file becomes the live programme docs page.

Test plan

  • Markdown file lints cleanly (table rendering, code blocks, MyST directives).
  • Docs build job picks up the new page under programs/gov/hmrc/.

🤖 Generated with Claude Code

#1654 is filed as a planning tracker. Persist the plan in-repo as a
"planned: not yet modelled" docs page under
docs/book/programs/gov/hmrc/benefits-in-kind.md so that:

- developers exploring the codebase find an honest "no BiK modelling
  today" stub rather than silence,
- the integration hook already in
  variables/household/benefits/employment_benefits.py is explicitly
  documented as the slot future work plugs into,
- the agreed Phase 1 MVP scope (company car, car fuel, private medical,
  living accommodation, beneficial loans), the FRS-vs-HMRC data gap, and
  the imputation approach are stable references that future per-category
  PRs can link to,
- the open questions about Class 1A NICs and UC treatment are preserved
  for the eventual scope discussion.

When the MVP lands the "planned" warning can be dropped and the page
converted into actual programme docs.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Plan: model benefits-in-kind (BiK) — scope, implementation, and data needs

1 participant