policyengine-code-organization
Code organization patterns for PolicyEngine - variable naming conventions, folder structure, file organization
When & Why to Use This Skill
This Claude skill provides a comprehensive framework for PolicyEngine code organization, focusing on standardized variable naming conventions, hierarchical folder structures, and consistent file organization. It ensures codebase maintainability and scalability by defining clear patterns for federal and state-level program implementations, including specific rules for eligibility, calculation, and deduction variables.
Use Cases
- Standardizing variable naming: Automatically apply correct state-specific prefixes and standard suffixes (e.g., _eligible, _countable_income) to ensure consistency across policy models.
- Project scaffolding: Determine the optimal folder structure (Flat, Light, or Full) based on the complexity and file count of a specific social safety net program.
- Code Review and Quality Assurance: Use the 'Common Mistakes to Avoid' guide to audit existing code for naming inconsistencies or incorrect test file structures.
- Test Automation Setup: Ensure integration and unit tests follow the mandatory naming patterns (e.g., integration.yaml) for seamless compatibility with the PolicyEngine testing suite.
- Developer Onboarding: Provide a quick-reference guide for new contributors to learn the specific terminology and architectural patterns required for PolicyEngine development.
| name | policyengine-code-organization |
|---|---|
| description | Code organization patterns for PolicyEngine - variable naming conventions, folder structure, file organization |
PolicyEngine Code Organization
Patterns for organizing PolicyEngine code - naming conventions, folder structure, and file organization.
Using the Variable Prefix
The variable prefix is defined in sources/working_references.md.
Look for this section:
## Official Program Name
**Federal Program**: [Federal program name]
**State's Official Name**: [State's official name]
**Abbreviation**: [Abbreviation]
**Source**: [Legal citation]
**Variable Prefix**: `[state]_[abbreviation]`
Use this prefix for all variable and parameter names.
Variable Naming Patterns
State Programs
# Pattern: {state}_{program}
az_liheap # Arizona LIHEAP
ca_calfresh # California CalFresh (SNAP)
ny_heap # New York HEAP (LIHEAP)
ma_snap # Massachusetts SNAP (uses federal name)
# Sub-variables: {state}_{program}_{component}
az_liheap_eligible
az_liheap_income_eligible
az_liheap_benefit_amount
Federal Programs
# Pattern: just {program}
snap
liheap
wic
# Sub-variables: {program}_{component}
snap_eligible
snap_gross_income
liheap_eligible
Standard Variable Components
Use these standard suffixes with your variable prefix:
Eligibility Variables
{prefix}_eligible # Final eligibility (combines all checks)
{prefix}_income_eligible # Income eligibility
{prefix}_resource_eligible # Resource/asset eligibility
{prefix}_categorical_eligible # Categorical eligibility
{prefix}_demographic_eligible # Age, household composition eligibility
{prefix}_immigration_eligible # Immigration status eligibility
Calculation Variables
{prefix} # Final benefit amount
{prefix}_maximum_benefit # Maximum possible benefit
{prefix}_countable_income # Income after deductions
{prefix}_countable_earned_income
{prefix}_countable_unearned_income
{prefix}_gross_income # Total income before deductions
Deduction/Disregard Variables
{prefix}_earned_income_disregard
{prefix}_work_expense_deduction
{prefix}_dependent_care_deduction
{prefix}_standard_deduction
Threshold/Limit Variables
{prefix}_income_limit
{prefix}_resource_limit
{prefix}_payment_standard
{prefix}_need_standard # Use state's terminology
State-Specific Terminology
Use the terminology from sources/working_references.md.
States use different terms for the same concepts:
| Concept | Possible Terms | Example |
|---|---|---|
| Benefit amount | Payment Standard, Need Standard, Grant Amount | {prefix}_need_standard |
| Income threshold | Gross Income Limit, GMI, Countable Income Limit | {prefix}_gmi_limit |
| Earnings deduction | Earned Income Disregard, Work Expense Deduction | {prefix}_earned_income_disregard |
Match the exact terms from the documentation.
Folder Organization Principles
Core Principles
- Group logically - Files that relate to the same aspect should be together
- Don't create subfolder for 1 file - If only 1 file for an aspect, keep it at parent level
- Final output at root - The main benefit variable (e.g.,
{prefix}.py) stays at the program folder root
Common Aspects (adapt to your program)
income/- Income calculations, limits, deductionseligibility/- Eligibility checksresources/- Asset/resource calculationsdeductions/- Deductions and disregards
Study Existing Implementations
Each program is different. Before organizing, look at similar programs in the codebase:
ls policyengine_us/variables/gov/states/{state}/{agency}/
Folder Structure Patterns
Small Program (~5 files) - Keep Flat
policyengine_us/variables/gov/states/{state}/{agency}/{program}/
├── {prefix}.py # Final benefit (at root)
├── {prefix}_eligible.py
├── {prefix}_income_eligible.py
├── {prefix}_maximum_benefit.py
└── {prefix}_countable_income.py
Medium Program (6-15 files) - Light Organization
policyengine_us/variables/gov/states/{state}/{agency}/{program}/
├── {prefix}.py # Final benefit (at root)
├── eligibility/
│ ├── {prefix}_eligible.py
│ ├── {prefix}_income_eligible.py
│ └── {prefix}_resource_eligible.py
└── income/
├── {prefix}_countable_income.py
└── {prefix}_gross_income.py
Large Program (>15 files) - Full Structure
policyengine_us/variables/gov/states/{state}/{agency}/{program}/
├── {prefix}.py # Final benefit (at root)
├── eligibility/
│ ├── {prefix}_eligible.py
│ ├── {prefix}_income_eligible.py
│ ├── {prefix}_resource_eligible.py
│ └── {prefix}_demographic_eligible.py
├── income/
│ ├── {prefix}_countable_income.py
│ ├── {prefix}_countable_earned_income.py
│ └── {prefix}_gross_income.py
└── deductions/
├── {prefix}_earned_income_disregard.py
└── {prefix}_work_expense_deduction.py
Tests
policyengine_us/tests/policy/baseline/gov/states/{state}/{agency}/{program}/
├── {prefix}.yaml
├── {prefix}_eligible.yaml
├── {prefix}_income_eligible.yaml
└── integration.yaml # Always named integration.yaml
Finding Existing Examples
To see naming patterns from similar programs:
# Find state programs
ls policyengine_us/variables/gov/states/{state}/
# Find similar program implementations
grep -r "class {state}_" policyengine_us/variables/gov/states/{state}/ | head -10
# Check parameter structure
ls policyengine_us/parameters/gov/states/{state}/{agency}/{program}/
Common Mistakes to Avoid
Variable Names
# ❌ WRONG - Using federal name when state has official name
ca_tanf_eligible # California calls it CalWORKs
# ✅ CORRECT - Using state's official name
ca_calworks_eligible
# ❌ WRONG - Inconsistent naming
az_liheap_benefit
az_liheap_eligible_status # Should be az_liheap_eligible
# ✅ CORRECT - Consistent pattern
az_liheap
az_liheap_eligible
Test File Names
# ❌ WRONG - Prefixed integration test
az_liheap_integration.yaml
# ✅ CORRECT - Standard integration test name
integration.yaml
# ❌ WRONG - Descriptive test names
test_low_income_family.yaml
# ✅ CORRECT - Variable-based test names
az_liheap.yaml
az_liheap_eligible.yaml
Quick Reference
| Element | Pattern | Example |
|---|---|---|
| Main benefit | {prefix} |
az_liheap |
| Eligibility | {prefix}_eligible |
az_liheap_eligible |
| Income eligibility | {prefix}_income_eligible |
az_liheap_income_eligible |
| Maximum benefit | {prefix}_maximum_benefit |
az_liheap_maximum_benefit |
| Integration test | integration.yaml |
integration.yaml |
| Unit test | {variable_name}.yaml |
az_liheap_eligible.yaml |