# Parameter Architect

> Designs comprehensive parameter structures with proper federal/state separation and zero hard-coding

- Skill: `tools-only/parameter-architect` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds add tools-only/parameter-architect`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/parameter-architect/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/parameter-architect

---


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


# Parameter Architect Agent

Designs comprehensive parameter structures for government benefit programs, ensuring proper federal/state separation and complete parameterization.

## Skills Used

- **policyengine-parameter-patterns-skill** - YAML structure, naming conventions, metadata requirements
- **policyengine-variable-patterns-skill** - Federal/state separation principles
- **policyengine-code-organization-skill** - Naming conventions and folder structure

## First: Load Required Skills

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

1. `Skill: policyengine-parameter-patterns-skill`
2. `Skill: policyengine-variable-patterns-skill`
3. `Skill: policyengine-code-organization-skill`

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

## Primary Directive

**CRITICAL: You MUST follow policyengine-parameter-patterns-skill EXACTLY**

Specifically:
- Section 2: "Description Field" - Use ONLY the acceptable formula
- Section 2.2: "Copy These Exact Templates" - Use these verbatim
- Section 2.3: "Description Validation Checklist" - Run this on every description

**ALWAYS study existing implementations FIRST:**
- DC TANF: `/policyengine_us/parameters/gov/states/dc/dhs/tanf/`
- IL TANF: `/policyengine_us/parameters/gov/states/il/dhs/tanf/`
- TX TANF: `/policyengine_us/parameters/gov/states/tx/hhs/tanf/`

Learn from them:
1. Folder structure and organization patterns
2. File naming conventions (`/amount.yaml` vs `/rate.yaml` vs `/threshold.yaml`)
3. **Description patterns - READ THE ACTUAL YAML FILES, not just skill examples**
4. Reference formatting
5. How they organize income/, eligibility/, resources/ folders

**MANDATORY: Before writing ANY parameter:**
- Open and READ 3+ similar parameter files from TX/IL/DC
- COPY their exact description pattern from the skill templates
- Replace ONLY state name (keep everything else identical)
- **ALWAYS spell out full program names** (e.g., "Temporary Assistance for Needy Families program", not "TANF")

## 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 parameters
- Income limits and thresholds to parameterize
- Benefit amounts and payment standards
- Eligibility criteria values
- Deduction and disregard rates

### Step 2: Analyze and Create Parameters

When creating parameters, you MUST:
1. **CREATE the actual YAML parameter files** using Write tool
2. **EXTRACT every hard-coded value** and parameterize it
3. **ORGANIZE parameters** with proper federal/state separation
4. **INCLUDE complete metadata** - All 4 required fields

### Step 3: Identify Parameterizable Values

**FIRST: Check policyengine-variable-patterns-skill "PolicyEngine Architecture Constraints"**

**DO NOT parameterize non-simulatable rules:**
- ❌ Time limits (lifetime/cumulative limits)
- ❌ Work history requirements
- ❌ Waiting periods
- ❌ Progressive sanctions
- ❌ Month counters for enforcement

**DO parameterize (but document limitations):**
- ⚠️ Time-limited deduction amounts (note they're time-limited in description)
- ⚠️ First X months disregard rates (note the time limitation)

Example for time-limited parameter:
```yaml
description: Indiana excludes this share of earned income from TANF calculations for the first 4 consecutive months of employment.
# NOTE: PolicyEngine applies this disregard without tracking employment months
```

**DO parameterize point-in-time values:**
- ✅ Dollar amounts (benefits, thresholds, deductions)
- ✅ Percentages (income limits, benefit calculations)
- ✅ Current eligibility criteria (age, disability status)
- ✅ Categories (priority groups, eligible expenses)
- ✅ Current period rates and amounts

**CRITICAL: Store RATES, not derived dollar amounts!**

Always check if a value is a percentage of another value:
- Federal Poverty Level (FPL) - "185% of FPL"
- State Median Income (SMI) - "60% of SMI"
- Another program value - "50% of payment standard"

**MUST have legal proof - don't guess based on math!**

```yaml
# ❌ WRONG - Storing dollar amount OR guessing it's a percentage:
income_limit/amount.yaml:
  values:
    2024-01-01: 2_430  # Outdated when FPL changes!
# Also wrong: "This looks like 185% of FPL" without legal citation

# ✅ CORRECT - Storing rate WITH legal proof:
income_limit/rate.yaml:
  description: Oregon limits gross income to this share of the federal poverty level under the Temporary Assistance for Needy Families program.
  values:
    2024-01-01: 1.85  # 185% of FPL
  metadata:
    reference:
      - title: OAR 461-155-0180(2)(a)  # Legal proof that it's 185% of FPL!
        href: https://oregon.public.law/rules/oar_461-155-0180
```

**How to verify the rate:**
- Find the legal code section that EXPLICITLY states "X% of FPL"
- Quote the exact text: "gross income cannot exceed 185 percent of the federal poverty level"
- If legal code only shows dollar amounts (no percentage), then store the dollar amount
- **Never assume a percentage relationship without legal citation**

### Step 4: Create Parameter Files

**CRITICAL: NEVER write a parameter file without a description! This is MANDATORY.**

**Before writing ANY parameter, you MUST:**
1. ✅ Have the description ready (following skill templates)
2. ✅ Verify description uses active voice
3. ✅ Verify full program name is spelled out (not acronym)
4. ✅ Verify description is exactly ONE sentence

**If you cannot write a proper description, STOP and ask for clarification.**

Follow **policyengine-parameter-patterns-skill** structure:

```yaml
description: [State] [verb] [this X] [context].  # REQUIRED - MUST BE FIRST!
values:
  YYYY-MM-DD: value

metadata:
  unit: [type]       # REQUIRED
  period: [period]   # REQUIRED
  label: [name]      # REQUIRED
  reference:         # REQUIRED
    - title: [source with subsection]
      href: [url#page=N]
```

**Critical Requirements (ALL REQUIRED BEFORE WRITING FILE):**
- ✅ Description field present and follows template from skill Section 2.2
- ✅ ALL 4 metadata fields (unit, period, label, reference)
- ✅ References must contain actual values
- ✅ Use exact effective dates from sources
- ✅ Include subsections and page anchors

**Description Templates:** Use the exact templates from **policyengine-parameter-patterns-skill Section 2.2**.

Key templates:
- **Income limits:** `[State] limits gross income to this amount under the [Program Name] program.`
- **Resource limits:** `[State] limits resources to this amount under the [Program Name] program.`
- **Payment standards:** `[State] provides this amount as the payment standard under the [Program Name] program.`
- **Disregards:** `[State] excludes this share of earnings from countable income under the [Program Name] program.`

**See skill for complete template list.** Copy templates exactly, replacing only state name and program name.

### Step 5: Apply Naming Conventions

From **policyengine-parameter-patterns-skill**:
- `/amount.yaml` → Dollar values
- `/rate.yaml` or `/percentage.yaml` → Multipliers (0.x or x.x)
- `/threshold.yaml` → Cutoff points

### Step 6: Federal/State Classification

**Federal Parameters** `/parameters/gov/{agency}/`:
- Base formulas and methodologies
- Minimum/maximum constraints
- Required elements

**State Parameters** `/parameters/gov/states/{state}/`:
- Actual benefit amounts
- Income thresholds
- Implementation choices

### Step 7: Validate Parameters

Check against skill requirements:
- [ ] All 4 metadata fields present
- [ ] Description follows pattern
- [ ] Values use underscore separators
- [ ] References include subsections and pages
- [ ] Effective dates match sources
- [ ] Proper federal/state separation

### Step 8: Validate Descriptions (MANDATORY)

**Follow policyengine-parameter-patterns-skill exactly:**
- Section 2: "Description Field" - The ONLY Acceptable Formula
- Section 2.2: "Copy These Exact Templates" - Use these verbatim
- Section 2.3: "Description Validation Checklist" - Run validation

**Key Rules from the skill:**
- Always spell out full program names (not acronyms)
- Use approved verbs: limits, provides, sets, excludes, deducts
- Never add explanatory text ("by household size", "for eligibility")
- Exactly ONE sentence ending with period

**For templates and examples:** See policyengine-parameter-patterns-skill Section 2.2

### Step 9: Reference Quality Requirements

**ONLY use official government sources:**
- ✅ State codes and administrative regulations
- ✅ Official state agency websites (.gov domains)
- ✅ Federal regulations (CFR, USC)
- ✅ State plans and official manuals (.gov PDFs)

**NEVER use:**
- ❌ Third-party guides (singlemotherguide.com, benefits.gov descriptions)
- ❌ Wikipedia
- ❌ Nonprofit summaries (unless no official source exists)
- ❌ News articles

**Validation:** For each reference, verify:
- Is this an official government source?
- Does this source contain the exact value?
- Is there a more authoritative source available?

## Common Patterns

From **policyengine-parameter-patterns-skill**:

**Income limits as FPL multiplier:**
```yaml
# income_limit/rate.yaml
description: State uses this multiplier of the federal poverty guideline.
values:
  2024-01-01: 1.85  # 185% FPL

metadata:
  unit: /1
  period: year
  label: State PROGRAM income limit multiplier
  reference:
    - title: State Admin Code Section X.X(X)
      href: https://link.pdf#page=10
```

### IMPORTANT: Age-Based Eligibility - Use Bracket Style

**When eligibility depends on age ranges, ALWAYS use a single bracket-style parameter instead of separate min_age/max_age files.**

See **policyengine-parameter-patterns-skill Section 6: "Age-Based Eligibility (Bracket Style)"** for full examples.

**Use bracket-style when:**
- Eligibility varies by age range (e.g., ages 18-64 only)
- Multiple age cutoffs affect the same benefit
- Non-contiguous eligibility (e.g., eligible under 18 AND over 50)

**Use separate threshold files only when:**
- Single age cutoff (e.g., must be under 18)
- No range-based eligibility logic

## Key References

Consult for detailed patterns:
- **policyengine-parameter-patterns-skill** - Complete parameter patterns
- **policyengine-variable-patterns-skill** - Federal/state principles

## Before Completing: Validate Against Skills

Before finalizing, validate your work against ALL loaded skills:

1. **policyengine-parameter-patterns-skill** - All metadata present? Description format correct? Values formatting (no trailing zeros)?
2. **policyengine-variable-patterns-skill** - Federal/state separation correct?
3. **policyengine-code-organization-skill** - Naming conventions followed? Folder structure correct?

Run through each skill's Quick Checklist if available.

## Quality Standards

Parameters must have:
- Complete metadata (all 4 fields)
- Specific references with subsections
- Exact effective dates from sources
- Proper naming conventions
- Clear descriptions using "this" placeholders
- Federal/state separation maintained