Guides PolicyEngine reform implementation with factory functions, contrib parameters, in_effect toggles, registration, test keys, and overrides for variables, organization, parameters.
From essentialnpx claudepluginhub policyengine/policyengine-claude --plugin data-scienceThis skill uses the workspace's default tool permissions.
Guides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.
Migrates code, prompts, and API calls from Claude Sonnet 4.0/4.5 or Opus 4.1 to Opus 4.5, updating model strings on Anthropic, AWS, GCP, Azure platforms.
Compresses source documents into lossless, LLM-optimized distillates preserving all facts and relationships. Use for 'distill documents' or 'create distillate' requests.
Comprehensive patterns for implementing policy reforms (proposed legislation, contributed tax/benefit changes) in policyengine-us. Reforms differ from baseline policy in that they are optional — toggled on/off via parameters — and live under contrib/ paths.
Baseline skills cover the foundational YAML/Python/test syntax. This skill covers the reform-specific layer on top.
When implementing a reform, this skill takes precedence over baseline skills wherever they conflict. The baseline skills (parameter-patterns, variable-patterns, code-organization, code-style, review-patterns) are written for enacted-law variables under variables/. Reforms have fundamentally different structure. The table below lists every known conflict:
| # | Baseline Rule (from skill) | Reform Override | Why |
|---|---|---|---|
| 1 | One variable per file in separate .py files under variables/ (code-organization, review-patterns) | All variables in ONE .py file inside the factory function closure under reforms/ | Reform variables must be defined inside the closure so the Reform class can reference them. Splitting into separate files breaks the factory pattern. |
| 2 | Folder structure — variables organized into eligibility/, income/, deductions/ subfolders (code-organization) | No subfolder tree — single .py file + __init__.py in reforms/states/{st}/{bill}/ | The reform's "organization" is sections within the single file, not a folder hierarchy. |
| 3 | Variables go in variables/gov/states/{st}/... (code-organization) | Reform variables go in reforms/states/{st}/{bill}/ or reforms/{org}/{topic}/ | Reform variables are NOT standalone — they're part of the reform module. |
| # | Baseline Rule (from skill) | Reform Override | Why |
|---|---|---|---|
| 4 | Exact dates from sources — never use arbitrary dates like 2000-01-01 (parameter-patterns) | in_effect.yaml MUST use 0000-01-01: false | This sentinel date means "false for all time until explicitly enabled." It's the only parameter that uses this pattern. All other reform parameters (amounts, rates, thresholds) still use exact dates from sources. |
| 5 | Description format: [State] [verb] [category] to [this X] under the [Full Program Name] program. (parameter-patterns) | in_effect.yaml uses: [State] [Bill Number] [short description] applies if this is true. Other reform params (amounts, rates) still follow baseline description rules. | The in_effect parameter describes a toggle, not a policy value. Only in_effect.yaml deviates — all other reform parameters follow baseline description format. |
| 6 | Label format: [State] [PROGRAM] [description] (parameter-patterns) | in_effect.yaml label: [ST] [Bill] [short name] in effect. Other reform params still follow baseline label rules. | Same rationale — only in_effect.yaml deviates. |
| # | Baseline Rule (from skill) | Reform Override | Why |
|---|---|---|---|
| 7 | Test path: tests/policy/baseline/gov/states/... (testing-patterns) | Reform test path: tests/policy/contrib/states/{st}/{bill}/ or tests/policy/contrib/{org}/{topic}/ | Different directory tree for contributed reforms. |
| 8 | No reforms: key — tests run against baseline automatically (testing-patterns) | Every test MUST have reforms: key with full dotted import path to the module-level bypass instance (e.g., reforms: policyengine_us.reforms.states.mt.hb268.mt_hb268_reform) | Without this key, the test runs against baseline code and the reform variables don't exist. |
| 9 | No parameter toggles in test input section (testing-patterns) | Every test MUST set gov.contrib.{...}.in_effect: true in the input section | The reform is off by default (0000-01-01: false). Tests must explicitly enable it or the reform logic won't execute. |
| 10 | Error margin: absolute_error_margin: 0.1 — "never use 1" (testing-patterns) | Reform tests commonly use absolute_error_margin: 1 | Reform calculations often involve larger numbers (tax amounts, credits) where $1 tolerance is appropriate. Use 0.1 only when testing boolean-like outputs. |
| 11 | Person names: always person1, person2 — never descriptive (testing-patterns) | Reform tests may use person1/child1 to clarify tax unit structure | Reform tests often need to distinguish adults from dependents for filing status and credit eligibility. child1 is acceptable when it clarifies the test setup. Follow whichever convention the existing reform tests in the codebase use. |
Summary for agents loading both baseline + reform skills:
reforms/ or params under gov/contrib/): follow this skill's rulesvariables/ or params under gov/states/): follow baseline skill rulesgov/contrib/ = reform rules apply| Type | Description | Parameter path | Variable location | Toggle |
|---|---|---|---|---|
| Baseline | Enacted law (current statute) | gov/states/{st}/... or gov/irs/... | variables/gov/states/{st}/... | None — always active |
| Contributed reform | Proposed bill or policy experiment | gov/contrib/states/{st}/{bill}/... or gov/contrib/{org}/{topic}/... | reforms/states/{st}/{bill}/... or reforms/{topic}/... | in_effect parameter |
| Enacted local tax | Enacted sub-state law | gov/local/{st}/{jurisdiction}/... | variables/gov/local/{st}/{jurisdiction}/... | None — always active |
Rule of thumb: If it's a bill number (HB, SB, AB, A0xxxx), a proposal, or a policy experiment, it's a contributed reform.
Every contributed reform follows this layout:
policyengine_us/
├── parameters/gov/contrib/states/{st}/{bill_id}/
│ ├── in_effect.yaml # Boolean toggle (REQUIRED)
│ ├── amount.yaml # Policy amounts
│ ├── age_limit.yaml # Eligibility thresholds
│ ├── rates.yaml # Rate brackets (or rates/ folder)
│ └── phaseout/ # Phase-out sub-parameters
│ ├── threshold.yaml # Often with filing_status breakdown
│ ├── rate.yaml
│ └── ...
│
├── reforms/states/{st}/{bill_id}/
│ ├── {reform_name}.py # Factory function + variable definitions
│ └── __init__.py # Exports
│
├── reforms/reforms.py # Registration (import + call factory)
│
├── tests/policy/contrib/states/{st}/{bill_id}/
│ └── {reform_name}.yaml # YAML test cases
│
└── changelog.d/{branch-name}.added.md # Changelog fragment
Federal reforms and organization-specific proposals (not state-specific) use a path without states/{st}:
parameters/gov/contrib/{org}/{topic}/... # e.g., gov/contrib/crfb/surtax/
reforms/{org}/{topic}/... # e.g., reforms/crfb/agi_surtax.py
tests/policy/contrib/{org}/{topic}/... # e.g., tests/policy/contrib/crfb/agi_surtax.yaml
When two related bills modify the same variables (e.g., KY HB 13 and HB 152 both change income tax brackets):
gov/contrib/states/ky/hb13/, gov/contrib/states/ky/hb152/)where(): where(hb13_active, hb13_result, where(hb152_active, hb152_result, baseline))in_effect Parameter (Required for Every Reform)Every reform MUST have an in_effect.yaml toggle:
description: >-
[State] [Bill Number] [short description] applies if this is true.
values:
0000-01-01: false
metadata:
unit: bool
period: year
label: "[ST] [Bill] [short name] in effect"
reference:
- title: "[Bill Number] - [Title]"
href: "https://legislature.gov/bills/..."
Key rules:
false (reform is off by default)0000-01-01 means "false for all time until explicitly enabled"true in their input sectionin_effect toggles (sub-feature pattern)A reform can have sub-features with their own in_effect toggles. The main reform can be active while a sub-feature is independently toggled:
gov/contrib/crfb/surtax/
├── in_effect.yaml # Main reform toggle
├── rate/
│ ├── single.yaml # Rate brackets for single filers
│ └── joint.yaml # Rate brackets for joint filers
└── increased_base/
├── in_effect.yaml # Sub-feature toggle (independent)
└── sources.yaml # Variable list for expanded base
In the formula, check both toggles:
def formula(tax_unit, period, parameters):
p = parameters(period).gov.contrib.crfb.surtax
# Main reform logic always runs (gated by outer factory function)
agi = tax_unit("adjusted_gross_income", period)
# Sub-feature: only if its own in_effect is true
if p.increased_base.in_effect:
additional = add(tax_unit, period, p.increased_base.sources)
agi = agi + additional
return p.rate.single.calc(agi)
Every reform Python file follows this two-function pattern:
from policyengine_core.model_api import *
from policyengine_us.model_api import *
from policyengine_core.periods import period as period_
def create_xx_reform() -> Reform:
"""Inner factory: defines variables and returns the Reform class."""
class some_variable(Variable):
value_type = float
entity = TaxUnit
label = "Description"
unit = USD
definition_period = YEAR
reference = "https://legislature.gov/bills/..."
defined_for = StateCode.XX
def formula(tax_unit, period, parameters):
p = parameters(period).gov.contrib.states.xx.bill_id
# ... calculation logic using p.amount, p.threshold, etc.
return result
class reform(Reform):
def apply(self):
self.update_variable(some_variable)
return reform
def create_xx_reform_reform(parameters, period, bypass: bool = False):
"""Outer factory: checks in_effect parameter before creating reform."""
if bypass:
return create_xx_reform()
p = parameters.gov.contrib.states.xx.bill_id
reform_active = False
current_period = period_(period)
for _ in range(5):
if p(current_period).in_effect:
reform_active = True
break
current_period = current_period.offset(1, "year")
if reform_active:
return create_xx_reform()
return None
# Module-level instance for direct test/import use
xx_reform = create_xx_reform_reform(None, None, bypass=True)
The outer function scans 5 years forward from the simulation period. This ensures reforms set to activate in a future year (e.g., 2027-01-01: true) are still loaded when simulating 2026.
bypass=True module-level instancexx_reform = create_xx_reform_reform(None, None, bypass=True)
This creates a reform object that bypasses parameter checks — used for:
reforms: path.to.module.xx_reform)in_effect check inside formulaFor simpler reforms, some implementations check in_effect inside the formula instead of the outer function. This avoids the 5-year lookahead complexity but means the reform class is always loaded:
def create_mi_surtax() -> Reform:
class mi_surtax(Variable):
defined_for = StateCode.MI
def formula(tax_unit, period, parameters):
p = parameters(period).gov.contrib.states.mi.surtax
in_effect = p.in_effect
surtax = p.rate.joint.calc(taxable_income)
return where(in_effect, surtax, 0)
class reform(Reform):
def apply(self):
self.update_variable(mi_surtax)
return reform
def create_mi_surtax_reform(parameters, period, bypass: bool = False):
return create_mi_surtax() # Always return — in_effect checked in formula
mi_surtax = create_mi_surtax_reform(None, None, bypass=True)
Prefer the standard 5-year lookahead pattern. Use the in-formula check only when you need the reform to always be structurally present (e.g., the variable must exist for other variables to reference it).
Reform variables are defined inside the factory function closure, NOT as standalone files in variables/.
class mt_newborn_credit(Variable):
value_type = float
entity = TaxUnit
label = "Montana newborn credit"
unit = USD
definition_period = YEAR
reference = "https://leg.mt.gov/bills/..."
defined_for = StateCode.MT # Or: defined_for = "eligibility_variable"
def formula(tax_unit, period, parameters):
p = parameters(period).gov.contrib.states.mt.newborn_credit
# ... calculation
return max_(base_credit - reduction, 0)
class sc_income_tax_before_non_refundable_credits(Variable):
value_type = float
entity = TaxUnit
label = "South Carolina income tax before non-refundable credits"
unit = USD
definition_period = YEAR
defined_for = StateCode.SC
def formula(tax_unit, period, parameters):
p = parameters(period).gov.contrib.states.sc.h4216
taxable_income = tax_unit("sc_taxable_income", period)
return p.rates.calc(taxable_income)
When overriding, use self.update_variable() in the Reform class — PolicyEngine replaces the baseline formula with yours.
When a reform applies only to qualifying taxpayers and others use baseline:
class ct_income_tax_after_personal_credits(Variable):
defined_for = StateCode.CT
def formula(tax_unit, period, parameters):
p_reform = parameters(period).gov.contrib.states.ct.sb100
p_baseline = parameters(period).gov.states.ct.tax.income
# Calculate both
reform_tax = p_reform.rates.single.calc(taxable_income)
baseline_tax = p_baseline.rates.calc(taxable_income)
# Select based on eligibility
qualifies = agi < p_reform.income_threshold[filing_status]
return where(qualifies, reform_tax, baseline_tax)
Used in repeal-style reforms:
class reform(Reform):
def apply(self):
self.neutralize_variable("al_dependent_exemption") # Sets to 0
self.update_variable(ga_exemptions) # Replace with reform version
When a reform needs to track which members of a group qualify and which don't:
class some_reform_eligible_count(Variable):
value_type = int
entity = TaxUnit
def formula(tax_unit, period, parameters):
p = parameters(period).gov.contrib.states.xx.bill
age = tax_unit.members("age", period)
eligible = age < p.age_limit
return tax_unit.sum(eligible)
class some_reform_credit(Variable):
value_type = float
entity = TaxUnit
def formula(tax_unit, period, parameters):
p = parameters(period).gov.contrib.states.xx.bill
eligible_count = tax_unit("some_reform_eligible_count", period)
ineligible_count = tax_unit("tax_unit_size", period) - eligible_count
# Different amounts for eligible vs ineligible members
return eligible_count * p.amount.eligible + ineligible_count * p.amount.ineligible
modify_parameters)When a reform creates a new credit, you must inject it into the state's existing credit list so the tax system recognizes it.
def create_mt_newborn_credit() -> Reform:
class mt_newborn_credit(Variable):
# ... variable definition ...
def modify_parameters(parameters):
# Get existing refundable credits list for the state
reform_credits = parameters.gov.states.mt.tax.income.credits.refundable
current_credits = reform_credits("2027-01-01") # Get current list
# Append the new credit variable name
updated_credits = current_credits + ["mt_newborn_credit"]
# Update for the reform's effective period
reform_credits.update(
start=instant("2027-01-01"),
stop=instant("2100-12-31"),
value=updated_credits,
)
return parameters
class reform(Reform):
def apply(self):
self.update_variable(mt_newborn_credit)
self.modify_parameters(modify_parameters)
return reform
Some reforms modify a parameter that holds a list of variable names (e.g., income sources). This uses the same modify_parameters pattern:
def modify_parameters(parameters):
# Example: modifying SALT deduction sources
parameters.gov.irs.deductions.itemized.salt_and_real_estate.sources.update(
start=instant("2025-01-01"),
stop=instant("2036-12-31"),
value=["real_estate_taxes"], # Replace list with just property taxes
)
return parameters
When to use modify_parameters:
credits.refundable list)credits.non_refundable list)When NOT needed:
For reforms that compute values from a configurable set of income sources, define the list as a parameter:
# gov/contrib/crfb/surtax/increased_base/sources.yaml
description: >-
The CRFB surtax increased base includes income from these sources.
values:
2025-01-01:
- traditional_401k_contributions
- roth_401k_contributions
- traditional_ira_contributions
- roth_ira_contributions
- health_savings_account_contributions
- student_loan_interest
- taxable_social_security
- tax_exempt_foreign_earned_income
- tax_exempt_interest_income
- health_insurance_premiums
metadata:
label: CRFB surtax increased AGI base sources
period: year
In the formula, use add() to sum the listed variables:
from policyengine_us.model_api import *
def formula(tax_unit, period, parameters):
p = parameters(period).gov.contrib.crfb.surtax
agi = tax_unit("adjusted_gross_income", period)
# If sub-feature is active, add the configurable sources
if p.increased_base.in_effect:
additional_sources = add(tax_unit, period, p.increased_base.sources)
agi = agi + additional_sources
filing_status = tax_unit("filing_status", period)
joint = filing_status == filing_status.possible_values.JOINT
return where(
joint,
p.rate.joint.calc(agi),
p.rate.single.calc(agi),
)
When to use this pattern:
reforms.pyEvery reform must be imported and registered in policyengine_us/reforms/reforms.py:
from policyengine_us.reforms.states.mt.newborn_credit import (
create_mt_newborn_credit_reform,
)
create_structural_reforms_from_parameters()def create_structural_reforms_from_parameters(parameters, period):
# ... other reforms ...
mt_newborn_credit = create_mt_newborn_credit_reform(parameters, period)
# ...
reforms = [
# ... other reforms ...
mt_newborn_credit,
]
# Filter out None (inactive reforms)
reforms = tuple(filter(lambda x: x is not None, reforms))
apply() class combined_reform(Reform):
def apply(self):
for reform in reforms:
reform.apply(self)
Note: The exact registration pattern varies. Some codebases use for reform in reforms: reform.apply(self) while others list each explicitly with None guards. Match the existing style in the file.
Reform tests use standard YAML format with two additions: the reforms: key and in_effect: true.
- name: Single filer with newborn, income below threshold
period: 2027
absolute_error_margin: 1
reforms: policyengine_us.reforms.states.mt.newborn_credit.mt_newborn_credit.mt_newborn_credit
input:
gov.contrib.states.mt.newborn_credit.in_effect: true
people:
person1:
age: 30
is_tax_unit_head: true
employment_income: 50_000
child1:
age: 0
is_tax_unit_dependent: true
tax_units:
tax_unit:
members: [person1, child1]
filing_status: SINGLE
households:
household:
members: [person1, child1]
state_code: MT
output:
mt_newborn_credit: 1_000
| Element | Description |
|---|---|
reforms: | Full dotted path to the module-level reform instance |
gov.contrib.{...}.in_effect: true | Enables the reform for this test |
state_code: XX | Ensures defined_for = StateCode.XX passes |
absolute_error_margin: 1 | Standard tolerance for floating-point |
reforms: pathThe path is the Python import path to the module-level bypass instance:
reforms: policyengine_us.reforms.states.{st}.{bill_id}.{module}.{instance_name}
Example: policyengine_us.reforms.crfb.agi_surtax.agi_surtax_reform_object
in_effect in testsWhen testing sub-features with their own in_effect toggle, set both:
input:
gov.contrib.crfb.surtax.in_effect: true
gov.contrib.crfb.surtax.increased_base.in_effect: true
Aim for comprehensive coverage across these categories:
in_effect: false (for reforms that use where(in_effect, reform_value, baseline_value) pattern)tests/policy/contrib/states/{st}/{bill_id}/{reform_name}.yaml
For federal/org reforms:
tests/policy/contrib/{org}/{topic}/{reform_name}.yaml
__init__.py Exports# reforms/states/{st}/{bill_id}/__init__.py
from .reform_name import create_xx_reform_reform, xx_reform
# reforms/states/{st}/__init__.py
from .bill_id import create_xx_reform_reform, xx_reform
echo "Added [State] [Bill Number] [short description] reform." > changelog.d/{branch-name}.added.md
Use .added for new reforms, .fixed for fixes to existing reforms.
Examples: MT newborn credit (#7513), CT refundable CTC (#7432), CT tax rebate (#7467), PA CTC (#7438)
Pattern:
in_effect, amount, eligibility thresholds, optional phase-outdefined_formodify_parameters: Adds variable name to state's credits.refundable listupdate_variable() + modify_parameters()Examples: CT SB-100 (#7474), KY HB 13/152 (#7397)
Pattern:
in_effect, new rate brackets (often per filing status).calc(taxable_income) on bracket parameterswhere() for income-based eligibilityExamples: SC H.4216 (#7494)
Pattern:
in_effect, rates, new deduction amounts, credit capsupdate_variable() callsExamples: NY A06774 enhanced CDCC (#7428), CT HB-5009 property tax credit (#7478)
Pattern:
in_effect, match rate or enhanced amounts, income thresholdwhere(eligible_for_enhanced, enhanced_value, standard_value)cdcc_potential instead of cdcc if the full variable depends on income taxExamples: Repeal state dependent exemptions (#7342)
Pattern:
neutralize_variable() zeros out targeted variablesupdate_variable() replaces others with reform-specific logicExamples: Streamlined EITC (#7110), CTC linear phase-out (#7110), CRFB AGI surtax (#7230)
Pattern:
gov/contrib/{org}/{topic}/ (no state prefix)defined_for = StateCode.XX (applies nationally)in_effect toggles for sub-features (see Section 3)When overriding a variable that feeds into income tax calculation, and income tax feeds back into your variable. Fix: Use intermediate variables that break the cycle (e.g., cdcc_potential instead of cdcc).
modify_parametersNew credits that aren't added to the state's credit list won't appear in the tax calculation. Always check if the variable needs to be registered in a credit/tax list.
When a reform uses AGI as the tax base instead of federal taxable income, don't include state_additions that undo federal deductions — they're already excluded. Add comments explaining this.
Same rule as baseline: ALL numeric values must come from parameters. No where(eligible, 1000, 0) — use where(eligible, p.amount, 0).
None in reforms listThe create_xx_reform() returns None when inactive. The reforms list in reforms.py must filter these out before combining.
Check if the legislation specifies rounding rules. Common patterns:
np.ceil() for ceiling (partial increments count as full)np.floor() for floor(amount // 10) * 10When accessing bracket parameters in Python, the bracket index goes on the scale node directly, NOT on a .brackets sub-path:
# ✅ Correct
p.rates.single[0].rate
p.rates.single.calc(taxable_income)
# ❌ Wrong
p.rates.single.brackets[0].rate
Many reforms have different thresholds or rates by filing status. Always check if the bill specifies different treatment for joint, single, HOH, etc.
parameters/gov/contrib/states/{st}/{bill_id}/in_effect.yaml (default: false)reforms/states/{st}/{bill_id}/{reform_name}.py with:
create_xx()) defining variables + Reform classcreate_xx_reform()) with 5-year lookaheadbypass=True instancereforms/states/{st}/{bill_id}/__init__.py with exportsreforms/reforms.py (import, instantiate, add to list, add to combined apply)modify_parameters() to inject into credit listtests/policy/contrib/states/{st}/{bill_id}/{reform_name}.yaml
reforms: key and in_effect: true in every testin_effect: test sub-features independentlychangelog.d/{branch-name}.added.mdmake format before committingWhen validating a reform implementation, check ALL of the following:
| # | Check | What to verify |
|---|---|---|
| 1 | in_effect.yaml exists | Default false, date 0000-01-01, under correct gov/contrib/ path |
| 2 | Parameter path correct | gov/contrib/states/{st}/{bill}/ or gov/contrib/{org}/{topic}/ |
| 3 | Factory pattern | Inner create_xx() returns Reform class, outer create_xx_reform() wraps with check |
| 4 | 5-year lookahead | Outer function scans 5 years forward (or uses in-formula check with justification) |
| 5 | Module-level instance | xx_reform = create_xx_reform(None, None, bypass=True) exported |
| 6 | Registration | Import + instantiate + list + combined apply in reforms.py |
| 7 | modify_parameters | Present if reform adds a NEW credit/tax to a list parameter |
| 8 | Test reforms: key | Every test has correct dotted import path to module-level instance |
| 9 | Test in_effect: true | Every test enables the reform via gov.contrib.{...}.in_effect: true |
| 10 | No hard-coded values | All amounts, rates, thresholds from parameters |
| 11 | defined_for | State reforms have defined_for = StateCode.XX |
| 12 | Filing status coverage | Tests cover at least SINGLE and JOINT |