Implement Tennessee TANF (Families First)

[hua7450]

Implement Tennessee TANF (Families First)

Overview

Implementation tracking issue for Tennessee TANF program (known as "Families First").

Status Checklist

• [ ] Documentation collected
• [ ] Parameters created
• [ ] Variables implemented
• [ ] Tests written
• [ ] CI passing
• [ ] PR ready for review

Documentation Summary

To be filled by document-collector agent

Program Overview

Tennessee's Temporary Assistance for Needy Families (TANF) program, branded as "Families First", provides cash assistance to low-income families with children.

Income Limits

Benefit Calculation

Eligibility Rules

Special Cases

References

• Tennessee Department of Human Services - Families First

Implementation Details

Parameter Files

Variable Files

Test Files

Branches

• Documentation: master
• Tests: test-tn-tanf-$(date +%Y%m%d)
• Implementation: impl-tn-tanf-$(date +%Y%m%d)
• Integration: integration-tn-tanf-$(date +%Y%m%d)

Related PRs

---

This issue serves as the central coordination point for all agents working on this implementation.

[hua7450]

Variable Naming Convention for Tennessee TANF (Families First)

ALL AGENTS MUST USE THESE EXACT NAMES:

Analysis of Existing Patterns

After analyzing existing state TANF implementations (DC, WA, IL, NY, TX, PA, etc.), I have identified the following consistent patterns:

Variable Naming Pattern

All state TANF programs follow the pattern: {state_code}_tanf_{component}

Examples from existing implementations:

• dc_tanf, dc_tanf_eligible, dc_tanf_countable_income
• wa_tanf, wa_tanf_eligible, wa_tanf_income_eligible
• il_tanf, il_tanf_eligible, il_tanf_countable_income
• ny_tanf, ny_tanf_eligible, ny_tanf_countable_earned_income
• tx_tanf, tx_tanf_eligible, tx_tanf_countable_resources

---

Primary Variables for Tennessee TANF

• Main benefit: tn_tanf
• Eligibility: tn_tanf_eligible
• Income eligibility: tn_tanf_income_eligible
• Resource eligibility: tn_tanf_resources_eligible

Supporting Variables (Common Pattern)

Based on typical TANF program structure:

Income Variables

• tn_tanf_countable_income
• tn_tanf_gross_earned_income
• tn_tanf_countable_earned_income
• tn_tanf_gross_unearned_income
• tn_tanf_countable_unearned_income

Resource Variables

• tn_tanf_countable_resources

Benefit Calculation

• tn_tanf_payment_standard or tn_tanf_maximum_benefit
• tn_tanf_need_standard (if applicable)

Deductions (if applicable)

• tn_tanf_dependent_care_deduction
• tn_tanf_work_expense_deduction
• etc.

---

Folder Structure

Variables:

/policyengine_us/variables/gov/states/tn/dhs/tanf/
├── tn_tanf.py
├── eligibility/
│   ├── tn_tanf_eligible.py
│   ├── tn_tanf_income_eligible.py
│   ├── tn_tanf_resources_eligible.py
│   └── ...
├── income/
│   ├── tn_tanf_countable_income.py
│   ├── earned/
│   │   ├── tn_tanf_gross_earned_income.py
│   │   ├── tn_tanf_countable_earned_income.py
│   │   └── ...
│   ├── unearned/
│   │   ├── tn_tanf_gross_unearned_income.py
│   │   ├── tn_tanf_countable_unearned_income.py
│   │   └── ...
│   └── deductions/
│       └── ...
└── benefit/
    ├── tn_tanf_payment_standard.py
    └── ...

Parameters:

/policyengine_us/parameters/gov/states/tn/dhs/tanf/
├── income/
│   ├── income_limit.yaml
│   ├── earned_income_disregard.yaml
│   └── ...
├── benefit/
│   ├── payment_standard.yaml
│   └── ...
├── resource_limit/
│   └── amount.yaml
└── ...

---

Naming Rationale

1. State Code: Use tn (lowercase, 2-letter state abbreviation) - consistent with all state programs
2. Program: Use tanf (not "families_first") - aligns with federal program name used across all states
3. Agency: Use dhs folder (Tennessee Department of Human Services) - follows pattern of PA, DC, IL
4. Component naming: Follow established patterns from other states:
   • _eligible for boolean eligibility variables
   • _countable_* for income/resources after exclusions and deductions
   • _gross_* for income before deductions
   • Organize into subdirectories: eligibility/, income/, benefit/, etc.

---

Test File Naming

Based on PolicyEngine conventions:

• Unit tests: Named after the variable being tested

  • tn_tanf.yaml
  • tn_tanf_eligible.yaml
  • tn_tanf_income_eligible.yaml
  • etc.

• Integration tests: Always named integration.yaml

  • NOT tn_tanf_integration.yaml
  • Place in the main tanf directory: /variables/gov/states/tn/dhs/tanf/integration.yaml

---

Special Considerations for Tennessee

1. Program Name: Tennessee's TANF is called "Families First" - this should be used in documentation and labels, but NOT in variable names

   • Variable: tn_tanf
   • Label: "Tennessee Families First (TANF)"

2. Entity: Based on common patterns, TANF benefits are calculated at SPMUnit level

3. Definition Period: Typically MONTH for TANF benefits

4. State Code: Use StateCode.TN for defined_for parameter

---

These names are final and based on consistent patterns across 10+ existing state TANF implementations. All agents must reference this naming convention.

🤖 Generated by Naming Coordinator Agent