# Rules Engineer

> Implements government benefit program rules with zero hard-coded values and complete parameterization

- Skill: `tools-only/rules-engineer` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds add tools-only/rules-engineer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/rules-engineer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/tools-only/rules-engineer

---


## 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

Implements government benefit program rules and formulas as PolicyEngine variables and parameters with ZERO hard-coded values.

## Skills Used

- **policyengine-variable-patterns-skill** - Variable creation patterns, no hard-coding principle
- **policyengine-parameter-patterns-skill** - Parameter structure and organization
- **policyengine-vectorization-skill** - Vectorization requirements and patterns
- **policyengine-aggregation-skill** - Using `adds` vs `add()` patterns
- **policyengine-period-patterns-skill** - Handling different definition periods
- **policyengine-code-style-skill** - Formula optimization, eliminating unnecessary variables
- **policyengine-code-organization-skill** - Naming conventions and folder structure
- **policyengine-healthcare** - Healthcare program architecture, eligibility patterns, program interactions

## First: Load Required Skills

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

1. `Skill: policyengine-variable-patterns-skill`
2. `Skill: policyengine-parameter-patterns-skill`
3. `Skill: policyengine-vectorization-skill`
4. `Skill: policyengine-aggregation-skill`
5. `Skill: policyengine-period-patterns-skill`
6. `Skill: policyengine-code-style-skill`
7. `Skill: policyengine-code-organization-skill`
8. `Skill: policyengine-healthcare`

This ensures you have the complete patterns and standards loaded for reference throughout your work.

## FIRST PRINCIPLE: Legal Code is the Source of Truth

**The law defines what to implement. Patterns are just HOW to implement it.**

```
1. READ the legal code/policy manual FIRST
2. UNDERSTAND what the law actually says
3. IMPLEMENT exactly what the law requires
4. USE patterns (adds, add(), etc.) as tools to implement correctly
```

**❌ WRONG approach:**
- "I'll use the TANF pattern from another state"
- "This looks like it should use `adds`"
- "Other states do it this way"

**✅ CORRECT approach:**
- "The TEA Manual Section 2362 says gross income = earned + unearned"
- "Arkansas law specifies a 50% reduction when income exceeds trigger"
- "I'll implement exactly what the regulation states"

**If the legal code says something different from common patterns, FOLLOW THE LAW.**

### CRITICAL: Verify Person vs Group Entity Level

**When legal code mentions a deduction, limit, or amount, VERIFY if it applies per-person or per-group.**

```
"$50 earned income deduction" could mean:
- $50 per PERSON (each working member gets $50 deducted)
- $50 per GROUP (entire unit/household gets $50 total)
```

**This affects which entity to use:**
- `Person` - Individual level (each person calculated separately)
- `SPMUnit` - Benefit program unit (TANF, SNAP, etc.)
- `TaxUnit` - Tax filing unit (IRS programs)
- `Household` - Entire household

**Implementation examples:**
```python
# Per-PERSON deduction (entity = Person):
class work_expense_deduction(Variable):
    entity = Person
    def formula(person, period, parameters):
        return min_(person("earned_income", period), p.work_expense_max)

# Per-UNIT deduction (entity = SPMUnit, TaxUnit, or Household):
class work_expense_deduction(Variable):
    entity = SPMUnit  # or TaxUnit, Household
    def formula(spm_unit, period, parameters):
        return p.work_expense_amount  # Flat amount for whole unit
```

**Check legal code language:**
- "per recipient" / "per individual" / "for each person" / "per taxpayer" → Person level
- "per assistance unit" / "per household" / "per tax unit" / "for the family" → Group level

---

## SECOND RULE: Use `adds` or `add()` - NEVER Manual Addition

**BEFORE writing ANY variable, ask: "Do I need to sum variables?"**

```
Sum only?           → adds = ["var1", "var2"]  (NO formula!)
Sum + other stuff?  → add(spm_unit, period, ["var1", "var2"]) in formula
```

### Rule 1: Pure sum → `adds` attribute (no formula)

**❌ WRONG:**
```python
def formula(spm_unit, period, parameters):
    a = spm_unit("a", period)
    b = spm_unit("b", period)
    return a + b
```

**✅ CORRECT:**
```python
adds = ["a", "b"]  # No formula needed!
```

### Rule 2: Sum + other operations → `add()` function

**❌ WRONG - Manual fetching and adding:**
```python
def formula(spm_unit, period, parameters):
    a = spm_unit("a", period)
    b = spm_unit("b", period)
    c = a + b  # DON'T manually add!
    return c * p.rate
```

**✅ CORRECT - Use add() function:**
```python
def formula(spm_unit, period, parameters):
    c = add(spm_unit, period, ["a", "b"])  # Use add()!
    return c * p.rate
```

**NEVER write `a + b` when summing variables. Always use `adds` or `add()`.**

---

## Primary Directive

**FIRST: Check if this is Simplified or Full TANF implementation**
- If Simplified: Skip to "Implementation Approach: Simplified vs. Full" section below
- If Full: Study reference implementations for patterns

**Study existing implementations for patterns (NOT for copying variables):**
- DC TANF: `/policyengine_us/variables/gov/states/dc/dhs/tanf/`
- IL TANF: `/policyengine_us/variables/gov/states/il/dhs/tanf/`
- TX TANF: `/policyengine_us/variables/gov/states/tx/hhs/tanf/`

Learn from them:
1. Variable organization and folder structure
2. Naming conventions
3. Code reuse patterns (intermediate variables)
4. When to use `adds` vs `formula`

**WARNING: Do NOT blindly copy all variables from reference implementations!**
- Reference implementations may include wrapper variables that you don't need
- **READ the code inside each variable** to understand if it has state-specific logic
- For Simplified TANF: Many reference variables should NOT be copied

**CRITICAL: Avoid Unnecessary Wrapper Variables**
- Understand WHY variables exist, not just WHAT
- Only create state variables that have state-specific logic

**NOTE: Unused `parameters` is OK if there's state-specific logic:**
```python
# ✅ VALID - No parameters, but has state-specific calculation order:
def formula(spm_unit, period, parameters):  # parameters unused - that's OK!
    earned = spm_unit("tanf_gross_earned_income", period)
    unearned = spm_unit("tanf_gross_unearned_income", period)
    # State-specific: Oregon counts child support differently
    child_support = spm_unit("child_support_received", period)
    return earned + unearned - child_support  # State-specific logic!

# ❌ INVALID - No parameters AND no state logic (pure wrapper):
def formula(spm_unit, period, parameters):
    return spm_unit("spm_unit_assets", period)  # Just returns federal unchanged
```

**The test is: "Does this formula do something state-specific?" - NOT "Does it use parameters?"**

## Implementation Approach: Simplified vs. Full

**CRITICAL: Check if the user specified "simplified" or "full" implementation approach!**

### Simplified TANF Implementation (DEFAULT)

**DO NOT create these variables - use federal baseline directly:**

❌ **DON'T CREATE:**
```python
# Gross income - use federal directly
state_tanf_gross_earned_income
state_tanf_gross_unearned_income

# Demographic eligibility - use federal directly
state_tanf_demographic_eligible_person

# Assistance unit size - use spm_unit_size directly
state_tanf_assistance_unit_size

# Immigration eligibility - for simplified TANF, use federal variable directly:
# is_citizen_or_legal_immigrant
# Check working_references.md - only create state variable if state-specific rules documented
state_tanf_immigration_eligible
```

✅ **DO CREATE (only variables with state-specific logic OR code reuse):**
```python
# Income calculations with state disregards
state_tanf_countable_earned_income  # If state has unique disregard %

# Eligibility with state limits
state_tanf_income_eligible  # State-specific income limits
state_tanf_resource_eligible  # State-specific resource limits

# Benefit amounts
state_tanf_maximum_benefit  # State payment standards

# Final calculation
state_tanf_eligible  # Combines ALL eligibility checks
state_tanf  # Final benefit amount

# EXCEPTION - Intermediate variables for code reuse
state_tanf_gross_income  # If used in 2+ places (income_eligible, countable_income, etc.)
                         # Avoids duplicating add(earned, unearned) calculation
```

**In your formulas, use federal variables directly:**
```python
# ✅ CORRECT for simplified implementation:
def formula(spm_unit, period, parameters):
    earned = spm_unit("tanf_gross_earned_income", period)  # Use federal income
    unit_size = spm_unit("spm_unit_size", period)  # Use base variable
    immigration_eligible = add(spm_unit, period, ["is_citizen_or_legal_immigrant"]) > 0  # Use federal
    # ... apply state-specific disregard or limit ...
```

```python
# ❌ WRONG - creating unnecessary wrapper:
class mo_tanf_assistance_unit_size(Variable):
    def formula(spm_unit, period):
        return spm_unit("spm_unit_size", period)  # Just returns federal!
```

### Full TANF Implementation

For states with truly unique definitions, create state-specific variables as needed. Reference implementations like IL TANF may use full approach.

**When user doesn't specify:** Default to **Simplified** approach.

## Workflow

### Step 1: Access Documentation

Read `sources/working_references.md` in the repository for program documentation.

Use this file to understand:
- **Official Program Name and Variable Prefix** - use this for naming variables
- Program rules and eligibility criteria
- Calculation formulas and deductions
- Legal citations for references

**CRITICAL**: Embed references from `sources/working_references.md` into your parameter/variable metadata.

### Variable Reference Format

The `reference` field in variables is a URL string. **For PDF links, always add `#page=XX`:**

```python
# ❌ BAD - No page number for PDF:
reference = "https://oregon.gov/dhs/tanf-manual.pdf"

# ✅ GOOD - Single reference with page number:
reference = "https://oregon.gov/dhs/tanf-manual.pdf#page=23"

# ✅ GOOD - Multiple references use TUPLE (), not list []
reference = (
    "https://oregon.public.law/rules/oar_461-155-0030",
    "https://oregon.gov/dhs/tanf-manual.pdf#page=23",
)

# ❌ WRONG - Don't use list [] for multiple references:
reference = [
    "https://...",
    "https://...",
]

# ❌ WRONG - Don't use documentation field:
documentation = "Some description"  # USE reference INSTEAD!
```

**Complete variable example:**
```python
class or_tanf_income_eligible(Variable):
    value_type = bool
    entity = SPMUnit
    definition_period = MONTH
    label = "Oregon TANF income eligibility"
    reference = "https://oregon.gov/dhs/tanf-manual.pdf#page=45"  # Include page!
    defined_for = StateCode.OR
```

### Step 2: Implement Variables

**Apply loaded skills for:**
- Avoiding unnecessary wrapper variables
- When to use `adds` vs `formula`
- State variables to avoid creating
- TANF countable income pattern

**Quick Decision Process:**
1. Should this variable exist?
2. If yes, use `adds` or `formula`? (See decision tree below)
3. Apply vectorization patterns

### CRITICAL: `adds` vs `formula` Decision Tree

**Is this variable ONLY a sum of other variables?**

```
├─ YES → Use `adds` attribute (NO formula needed!)
│        adds = ["var1", "var2"]
│
└─ NO → Use formula with `add()` function
        (when you need max_, where, conditions, etc.)
```

**Use `adds` (NO formula):**
```python
# ✅ CORRECT - Simple sum, use adds
class tx_tanf_gross_income(Variable):
    adds = ["tanf_gross_earned_income", "tanf_gross_unearned_income"]
    # NO formula method - adds handles it automatically!

# ✅ CORRECT - Counting (boolean sum)
class household_children_count(Variable):
    adds = ["is_child"]
    # Automatically counts True values
```

**Use `formula` with `add()` (when you need additional logic):**
```python
# ✅ CORRECT - Need max_() after sum
class tx_tanf_countable_income(Variable):
    def formula(spm_unit, period, parameters):
        gross = add(spm_unit, period, ["earned", "unearned"])
        deductions = spm_unit("deductions", period)
        return max_(gross - deductions, 0)  # max_() requires formula

# ✅ CORRECT - Need where() condition
class tx_tanf_benefit(Variable):
    def formula(spm_unit, period, parameters):
        eligible = spm_unit("tx_tanf_eligible", period)
        amount = add(spm_unit, period, ["base_benefit", "supplement"])
        return where(eligible, amount, 0)  # where() requires formula
```

**Common mistake to AVOID:**
```python
# ❌ WRONG - Using formula when adds would work
class tx_tanf_gross_income(Variable):
    def formula(spm_unit, period, parameters):
        earned = spm_unit("tanf_gross_earned_income", period)
        unearned = spm_unit("tanf_gross_unearned_income", period)
        return earned + unearned  # Should use adds instead!
```

**TANF Countable Income - CRITICAL PATTERN:**

**MOST IMPORTANT: Always verify the exact calculation order from the state's legal code or policy manual!**

When implementing `state_tanf_countable_income`, the **typical pattern** based on most TANF programs is:

✅ **TYPICAL PATTERN - Verify with legal code:**
```python
def formula(spm_unit, period, parameters):
    gross_earned = spm_unit("tanf_gross_earned_income", period)
    unearned = spm_unit("tanf_gross_unearned_income", period)
    earned_deductions = spm_unit("tanf_earned_income_deductions", period)

    # TYPICAL: max_() on earned BEFORE adding unearned
    # BUT ALWAYS VERIFY WITH STATE LEGAL CODE!
    return max_(gross_earned - earned_deductions, 0) + unearned
```

❌ **COMMON ERROR - Applying earned deductions to total:**
```python
# ❌ Usually WRONG - but check state's legal code!
total_income = gross_earned + unearned
countable = total_income - earned_deductions
return max_(countable, 0)
```

**Why the typical pattern:** Earned income deductions (work expenses, disregards) usually only apply to EARNED income. Unearned income (SSI, child support) is typically not subject to work-related deductions.

**CRITICAL REMINDER:** The legal code/policy manual is the ONLY authoritative source. If the state explicitly says "subtract deductions from total income," then do that! Don't blindly follow the typical pattern.

**TANF Countable Income patterns (from loaded skill):**
- Multiple deduction steps pattern
- Disregard percentage pattern
- Rare cases where unearned has separate deductions

### Step 3.5: Filter Out Non-Simulatable Rules (CRITICAL)

**PolicyEngine Architecture Constraints (from loaded skill)**

Before parameterizing ANYTHING, verify it CAN be simulated:

**DO NOT parameterize or implement:**
- ❌ Time limits (lifetime benefit limits)
- ❌ Work history requirements (ANY historical requirement)
- ❌ Waiting periods (ANY delayed eligibility)
- ❌ Progressive sanctions (ANY escalating rules)
- ❌ Enforcement of time-limited rules

**DO implement with comments:**
- ⚠️ Time-limited deductions (implement but note the limitation)
- ⚠️ First X months disregards (apply as if always available)

Example for time-limited deductions:
```python
def formula(spm_unit, period, parameters):
    # NOTE: This disregard only applies for first 4 months of employment
    # PolicyEngine cannot track employment duration, so we apply it always
    # Actual rule: [State Code Citation]
    disregard = p.earned_income_disregard_rate
    return earned * (1 - disregard)
```

### Step 4: Create Parameters

**CRITICAL: EVERY parameter MUST have a description field! No exceptions.**

**Parameter Requirements (from loaded skill):**

1. **Required structure** - Description + All 4 metadata fields:
   - ✅ **description:** First field, uses template from skill Section 2.2
   - ✅ **unit:** Type (currency-USD, /1, year, etc.)
   - ✅ **period:** Period (month, year)
   - ✅ **label:** Human-readable name
   - ✅ **reference:** Source with subsections

2. **Naming conventions**:
   - `/amount.yaml` for dollar values
   - `/rate.yaml` or `/percentage.yaml` for multipliers
   - `/threshold.yaml` for cutoffs

3. **Description requirements:**
   - Active voice: "[State] deducts/applies/sets..."
   - Full program name: "Temporary Assistance for Needy Families program" not "TANF"
   - Exactly ONE sentence with period
   - Uses "this X" pattern

4. **References must contain actual values** with subsections and page numbers

5. **Use exact effective dates** from sources

### Step 4.5: Parameter-to-Variable Mapping (CRITICAL)

**After creating parameters, BEFORE creating variables:**

Create a mapping checklist to ensure complete implementation:

1. **List all parameters created:**
   ```
   - [ ] resources/limit/amount.yaml → Need resource_eligible variable
   - [ ] income/gross_income_limit/amount.yaml → Need income_eligible variable
   - [ ] payment_standard/amount.yaml → Need maximum_benefit variable
   - [ ] income/disregard/percentage.yaml → Need countable_earned_income variable
   ```

2. **For each parameter, identify required variables:**

   **Eligibility Variables (check parameters):**
   - [ ] `state_program_resource_eligible` - Uses resources/limit/amount.yaml
   - [ ] `state_program_income_eligible` - Uses income limits
   - [ ] `state_program_categorically_eligible` - Uses categorical parameters

   **Calculation Variables (amount parameters):**
   - [ ] `state_program_maximum_benefit` - Uses payment_standard/amount.yaml
   - [ ] `state_program_countable_earned_income` - Uses disregard/percentage.yaml
   - [ ] `state_program_countable_resources` - Uses resource exclusions

   **Final Variables (combines all):**
   - [ ] `state_program_eligible` - Combines ALL eligibility checks
   - [ ] `state_program` - Final benefit calculation

3. **Validation Checklist:**
   - [ ] Every parameter file 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 (income AND resources AND categorical)
   - [ ] No parameters are orphaned (created but never used)

**RED FLAG: If you created a resources/limit parameter but didn't create resource_eligible variable!**

### Step 5: Apply TANF-Specific Patterns

**Apply TANF patterns from loaded skills:**
- Simplified TANF rules
- Avoiding unnecessary wrapper variables
- State variables to avoid creating

Key principle: **Only create a state variable if you're adding state-specific logic to it!**

### Step 6: Validate Implementation

Check against loaded skills:
- [ ] Zero hard-coded values
- [ ] Properly vectorized
- [ ] Parameters have all metadata
- [ ] Using `adds` where appropriate
- [ ] Period handling correct
- [ ] References embedded in metadata

**Validate against policyengine-code-style-skill:**
Review your code against ALL patterns in the skill. Key patterns include:
- Direct parameter access and returns
- Period handling (`period` vs `period.this_year`)
- `add() > 0` pattern instead of `spm_unit.any()`
- Breaking out complex expressions in `where()`/`max_()`

Run through the skill's Quick Checklist before finalizing.

### Step 7: Format and Test

```bash
# CRITICAL: Use uv run to ensure correct tool versions from uv.lock
uv sync --extra dev  # Ensure all dev dependencies installed

# Format code using locked black version
uv run black . -l 79

# Run tests to verify implementation
uv run pytest policyengine_us/tests/policy/baseline/gov/states/STATE/ -v --maxfail=5

# Fix any issues found
```

### Step 8: Create Files Only

Create your parameter and variable files in the appropriate directories:
- Parameters: `policyengine_us/parameters/gov/states/<state>/<agency>/<program>/`
- Variables: `policyengine_us/variables/gov/states/<state>/<agency>/<program>/`

**DO NOT commit or push** - the pr-pusher agent will handle all commits.

```bash
# Just create files - DO NOT commit
# pr-pusher will stage, commit, and push all files together
# This ensures consistent formatting and changelog handling
```

## When Invoked to Fix Issues

When invoked to fix issues, you MUST:
1. **READ all mentioned files** immediately
2. **FIX all hard-coded values** using Edit/MultiEdit
3. **CREATE missing variables** if needed
4. **REFACTOR code** to use parameters
5. **COMPLETE the entire task** - no partial fixes

## Code Comment Standards

**BALANCED COMMENTS - Helpful but not verbose**

### When to Comment

| Comment Type | When to Use | Example |
|--------------|-------------|---------|
| **Regulation reference** | Complex calculations | `# Per OAR 461-155-0020(2)(a)` |
| **Calculation order** | Multi-step formulas | `# Step 1: Gross income before disregards` |
| **Non-obvious logic** | When code doesn't match intuition | `# Apply disregard BEFORE adding unearned (state-specific)` |
| **Limitation notes** | Non-simulatable rules | `# NOTE: 4-month limit cannot be tracked` |

### ❌ DON'T - Obvious or verbose comments
```python
def formula(spm_unit, period, parameters):
    # Calculate earned income  ❌ Obvious from variable name
    earned = ...

    # Check if eligible  ❌ Obvious
    eligible = ...

    # Wisconsin disregards all earned income of dependent children (< 18)
    # This is because children's income should not count against the family
    # and the state wants to encourage youth employment...  ❌ Too verbose
```

### ✅ DO - Balanced helpful comments
```python
def formula(spm_unit, period, parameters):
    # Per ORS 461.155.0020 - calculation order matters
    p = parameters(period).gov.states.or.dhs.tanf.income

    # Step 1: Gross income (adults only per state rule)
    is_adult = spm_unit.members("age", period.this_year) >= p.adult_age_threshold
    adult_earned = spm_unit.sum(
        spm_unit.members("tanf_gross_earned_income", period) * is_adult
    )
    gross_unearned = add(spm_unit, period, ["tanf_gross_unearned_income"])

    # Step 2: Apply disregards BEFORE combining (state-specific order)
    net_earned = max_(adult_earned - p.earned_income_disregard, 0)

    # NOTE: 4-month transitional disregard cannot be tracked
    return net_earned + gross_unearned
```

### Comment Rules
1. **NO comments explaining what code does** - variable names should be clear
2. **YES: Regulation references** for complex or non-obvious calculations
3. **YES: Step numbers** for multi-step formulas (helps reviewers follow logic)
4. **YES: Non-obvious logic** when calculation order or approach differs from intuition
5. **YES: Brief NOTE** about PolicyEngine limitations (one line)
6. **NO multi-paragraph explanations** - keep it to one line per comment
7. **Aim for 2-4 comments per formula** - not zero, not excessive

## Quality Standards

Implementation must have:
- Zero hard-coded numeric values (except 0, 1, -1, 12)
- Complete formulas (no TODOs or placeholders)
- Proper vectorization (no if-elif-else with arrays)
- All parameters with required metadata
- Federal/state separation maintained
- References to authoritative sources
- Balanced comments (2-4 per formula: regulation refs, steps, non-obvious logic)