Skip to content

Document future-date policy announcements (#636)#1727

Open
vahid-ahmadi wants to merge 1 commit into
mainfrom
vahid-ahmadi/issue-636-future-date-announcements-doc
Open

Document future-date policy announcements (#636)#1727
vahid-ahmadi wants to merge 1 commit into
mainfrom
vahid-ahmadi/issue-636-future-date-announcements-doc

Conversation

@vahid-ahmadi
Copy link
Copy Markdown
Collaborator

Summary

  • Future-date today's policy announcements #636 (filed in 2022, motivated by the Truss "growth plan" tax cuts) asked for an explicit way to encode announced-but-not-yet-implemented policy changes.
  • The feature has been live the whole time — date-keyed parameter values are the underlying mechanism and the repo is full of working examples (NI Levy then-cut, Budget 2025 two-child limit removal, PA freeze extension) — but it wasn't documented as a pattern.
  • New docs page at docs/book/policy/future-date-announcements.md covering:
    • the mechanism (parameter values keyed by effective date, latest on-or-before query date wins),
    • three common patterns: announced-then-reversed (Truss mini-budget), phased-in changes, announced abolitions/sunsets,
    • best practices: cite every future-dated row, don't extrapolate beyond what was announced, use policy_date queries for back-cast scenarios,
    • distinction from gov.contrib.* reform parameters (uncertain / hypothetical) vs baseline future-dated rows (announced policy).
  • Cross-links to the worked example in child-poverty-tcl.md (Validate PolicyEngine child poverty estimates against RF/OBR benchmarks #1398) and the Truss-era blog post.
  • Pure documentation; no code changes.

Test plan

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

🤖 Generated with Claude Code

#636 (2022) asked for an explicit way to encode announced-but-not-yet-
implemented policy changes, citing the Truss "growth plan" tax cuts as
the motivating example. The feature has been live the whole time — the
date-keyed parameter values mechanism handles it natively — but it
wasn't documented.

Persist the pattern in-repo at docs/book/policy/future-date-announcements.md
covering:

- the mechanism (parameter values keyed by effective date, latest on
  or before the query date wins),
- the three common patterns:
  * announced-then-reversed (Truss mini-budget): two rows, one at
    announcement date with the announced value, one at reversal date
    with the actual landing value;
  * phased-in changes: one row per phase with separate references
    (NI thresholds through the Health & Social Care Levy + April 2024
    cuts as a worked example);
  * announced abolitions: limit value up to the effective date, then
    sentinel (.inf or 0) from that date onwards (Budget 2025
    two-child limit removal as the cross-link),
- best practices: cite every future-dated row, don't extrapolate
  beyond what was announced, use policy_date queries for back-cast
  scenarios,
- distinction from gov.contrib.* reform parameters (uncertain /
  hypothetical) vs baseline future-dated rows (announced policy).
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.

1 participant