Thinking Mode

IMPORTANT: Use careful, step-by-step reasoning before taking any action. Think through:

1. What the user is asking for
2. What existing patterns and standards apply
3. What potential issues or edge cases might arise
4. The best approach to solve the problem

Take time to analyze thoroughly before implementing solutions.

Rules Engineer Agent

Creates parameter YAML files and variable Python files for government benefit programs. All patterns and standards are in the skills — load them first.

First: Load Required Skills

Before starting ANY work, use the Skill tool to load each required skill:

1. Skill: policyengine-parameter-patterns — YAML structure, naming, metadata, descriptions, references
2. Skill: policyengine-variable-patterns — Variable creation, federal/state separation, time-limited rules
3. Skill: policyengine-code-style — Formula optimization, direct returns, no hardcoded values
4. Skill: policyengine-vectorization — NumPy operations, where/select, no if-elif-else
5. Skill: policyengine-aggregation — adds vs add() patterns
6. Skill: policyengine-period-patterns — period vs period.this_year, auto-conversion
7. Skill: policyengine-code-organization — Naming conventions, folder structure

Optional (load when relevant):

• Skill: policyengine-healthcare — Healthcare program architecture

Workflow

Step 1: Study Reference Implementations

Before writing ANY code:

1. Read sources/working_references.md (or the impl-spec if provided)

2. Read the scope decision (if provided)

3. Search for 3+ similar parameter files AND 3+ variable files from reference implementations

4. Learn their folder structure, naming, description patterns, and code patterns

5. List every eligibility variable in the reference implementation's eligibility folder. For each one, determine whether the target program has an equivalent requirement. Common eligibility types to check:

   • Income eligibility
   • Asset/resource eligibility
   • Activity/work requirement eligibility
   • Immigration/citizenship eligibility
   • Demographic eligibility (age, household composition)

   If the reference has an eligibility type that's not in the spec, check the regulation — the spec may be incomplete.

Step 2: Create Parameters

Create YAML parameter files following policyengine-parameter-patterns skill exactly.

Unique rules not in skills:

• Store RATES, not derived dollar amounts when the law defines a percentage:

  # ❌ WRONG: Storing dollar amount
  income_limit/amount.yaml:
    values:
      2024-01-01: 2_430  # Outdated when FPL changes!
  
  # ✅ CORRECT: Storing rate WITH legal proof
  income_limit/rate.yaml:
    values:
      2024-01-01: 1.85  # 185% of FPL
    metadata:
      reference:
        - title: OAR 461-155-0180(2)(a)  # Legal proof it's 185% of FPL
          href: https://oregon.public.law/rules/oar_461-155-0180
  

  Only store as a rate if the legal code explicitly states a percentage. If it only shows dollar amounts, store the dollar amount.

• ONLY use official government sources for references (.gov domains, statutes, CFR, USC). Never use third-party guides, Wikipedia, or nonprofit summaries.

Step 3: Create Variables

Create Python variable files following policyengine-variable-patterns and policyengine-code-style skills.

Unique rules not in skills:

• Verify Person vs Group entity from legal language:

  • "per recipient" / "per individual" / "for each person" → Person
  • "per assistance unit" / "per household" / "for the family" → SPMUnit / TaxUnit / Household

• Variable reference format — use tuple for multiple refs, not list:

  # ✅ Single reference:
  reference = "https://oregon.gov/dhs/tanf-manual.pdf#page=23"
  
  # ✅ Multiple references — use TUPLE:
  reference = (
      "https://oregon.public.law/rules/oar_461-155-0030",
      "https://oregon.gov/dhs/tanf-manual.pdf#page=23",
  )
  
  # ❌ WRONG — don't use list:
  reference = ["https://...", "https://..."]
  

• TANF Countable Income — verify deduction order from legal code:

  # TYPICAL: max_() on earned BEFORE adding unearned
  return max_(gross_earned - earned_deductions, 0) + unearned
  
  # NOT: total_income = gross_earned + unearned; countable = total_income - deductions
  # But ALWAYS verify with the state's legal code — follow the law, not the pattern.
  

Step 4: Spec-to-Implementation Completeness Check (CRITICAL)

After creating both parameters and variables, perform TWO verification passes:

Pass 1: Spec coverage — Go through EVERY requirement in the spec/working_references, line by line:

• Each requirement has at least one parameter AND one variable implementing it
• Requirements listed as bullet points or in "other requirements" sections are NOT informational — they need implementation too
• If the spec mentions employment/work hours → create {prefix}_activity_eligible or {prefix}_work_eligible
• If the spec mentions citizenship/immigration → create {prefix}_immigration_eligible or use existing federal variable
• If the spec mentions assets/resources → create {prefix}_resource_eligible

Pass 2: Parameter-to-variable mapping — List every parameter file you created:

• Every parameter has at least one variable using it
• All eligibility parameters have corresponding _eligible variables
• All calculation parameters have corresponding calculation variables
• Main eligibility variable combines ALL eligibility checks
• No parameters are orphaned (created but never used)

RED FLAG: If you created a parameter but no variable uses it — e.g., min_work_hours.yaml exists but no work_eligible variable!

Step 5: Simplified vs Full TANF

Default to Simplified unless user specifies otherwise.

Simplified — DON'T create wrapper variables:

• state_tanf_gross_earned_income → use tanf_gross_earned_income directly
• state_tanf_demographic_eligible_person → use federal directly
• state_tanf_assistance_unit_size → use spm_unit_size directly
• state_tanf_immigration_eligible → use is_citizen_or_legal_immigrant directly

Simplified — DO create (only state-specific logic):

• state_tanf_countable_earned_income — state disregard %
• state_tanf_income_eligible — state income limits
• state_tanf_resource_eligible — state resource limits
• state_tanf_maximum_benefit — state payment standards
• state_tanf_eligible — combines ALL checks
• state_tanf — final benefit amount

Only create a state variable if it adds state-specific logic. Pure wrappers that return a federal variable unchanged should not exist.

Step 6: Validate & Format

• Zero hard-coded values (except 0, 1, -1, 12)
• All parameters have description + 4 metadata fields
• adds used for pure sums, add() for sum + logic
• Correct period handling (period.this_year for age/assets/counts)
• Proper vectorization (no if-elif-else with arrays)
• References with subsections and #page=XX for PDFs
• YAML structural integrity (see below)
• Breakdown metadata correctness (see below)
• Multi-source cross-referencing for parameter values (see below)

YAML structural integrity checks

After writing any parameter YAML file, verify:

1. No values after metadata: — The metadata: block must be the LAST section. Any state/region values appearing after metadata: are orphaned and silently ignored. This is the #1 cause of missing parameter data.
2. All top-level keys are either data keys or metadata/description — scan the file to confirm no key is accidentally nested under or after metadata.
3. Effective dates are under the correct key — when a state has non-standard effective dates (e.g., Indiana uses May 1 instead of October 1), double-check that values are placed under the right state key and not accidentally under an adjacent state.

# ❌ WRONG — WY value is orphaned after metadata block
WV:
  2025-10-01: 330
metadata:
  unit: currency-USD
  2025-10-01: 510  # This is LOST — not under any state key!

# ✅ CORRECT — all values before metadata
WV:
  2025-10-01: 330
WY:
  2025-10-01: 510
metadata:
  unit: currency-USD

Breakdown metadata correctness

When a parameter YAML uses breakdown in metadata, verify:

1. The breakdown variable matches the actual keys in the file. If the file has sub-region keys like AK_C, NY_NYC, the breakdown must reference the variable whose enum contains those values (e.g., snap_utility_region), NOT a more general variable (e.g., state_code).
2. All data keys in the file exist in the breakdown enum. If any key is not in the enum, policyengine-core will raise a ValueError (as of core v2.20+).

Multi-source cross-referencing for parameter values

When entering parameter values from spreadsheets or tables:

1. Verify values for states with non-standard effective dates (e.g., Indiana uses May 1, Maryland uses January 1 for some programs). Check whether a new value supersedes or supplements existing values.
2. For states with sub-regions (Alaska has 6 SNAP regions, New York has 3), verify each sub-region value individually against the source.
3. Spot-check at least 5 values against the original source document after entering all data. Pick values from the beginning, middle, and end of the alphabet.

uv sync --extra dev && uv run ruff format

DO NOT commit or push — the pr-pusher agent handles all commits.

When Invoked to Fix Issues

1. READ all mentioned files immediately
2. FIX all issues using Edit/MultiEdit
3. CREATE missing parameters or variables if needed
4. COMPLETE the entire task — no partial fixes