gh-policyengine-policyengine-claude/commands/encode-policy.md

description

description
Orchestrates multi-agent workflow to implement new government benefit programs

Implementing $ARGUMENTS in PolicyEngine

Coordinate the multi-agent workflow to implement $ARGUMENTS as a complete, production-ready government benefit program.

Program Type Detection

This workflow adapts based on the type of program being implemented:

TANF/Benefit Programs (e.g., state TANF, SNAP, WIC):

• Phase 4: test-creator creates both unit and integration tests
• Phase 7: Uses specialized @complete:country-models:tanf-program-reviewer agent in parallel validation
• Optional phases: May be skipped for simplified implementations

Other Government Programs (e.g., tax credits, deductions):

• Phase 4: test-creator creates both unit and integration tests
• Phase 7: Uses general @complete:country-models:implementation-validator agent in parallel validation
• Optional phases: Include based on production requirements

Phase 0: Implementation Approach (TANF Programs Only)

For TANF programs, detect implementation approach from $ARGUMENTS:

Auto-detect from user's request:

• If $ARGUMENTS contains "simple" or "simplified" → Use Simplified approach
• If $ARGUMENTS contains "full" or "complete" → Use Full approach
• If unclear → Default to Simplified approach

Simplified Implementation:

• Use federal baseline for gross income, demographic eligibility, immigration eligibility
• Faster implementation
• Suitable for most states that follow federal definitions
• Only creates state-specific variables for: income limits, disregards, benefit amounts, final calculation

Full Implementation:

• Create state-specific income definitions, eligibility criteria
• More detailed implementation
• Required when state has unique income definitions or eligibility rules
• Creates all state-specific variables

Record the detected approach and pass it to Phase 4 (rules-engineer).

Phase 1: Issue and PR Setup

Invoke @complete:country-models:issue-manager agent to:

• Search for existing issue or create new one for $ARGUMENTS
• Create draft PR immediately in PolicyEngine/policyengine-us repository (NOT personal fork)
• Return issue number and PR URL for tracking

Phase 2: Variable Naming Convention

Invoke @complete:country-models:naming-coordinator agent to:

• Analyze existing naming patterns in the codebase
• Establish variable naming convention for $ARGUMENTS
• Analyze existing folder structure patterns in the codebase
• Post naming decisions and folder structure to GitHub issue for all agents to reference

Quality Gate: Naming convention and folder structure must be documented before proceeding to ensure consistency across parallel development.

Phase 3: Document Collection

Phase 3A: Initial Document Gathering

Invoke @complete:country-models:document-collector agent to gather official $ARGUMENTS documentation, save as working_references.md in the repository, and post to GitHub issue

After agent completes:

1. Check the agent's report for "📄 PDFs Requiring Extraction" section

2. Decision Point:

   • If PDFs are CRITICAL (State Plans with benefit formulas, calculation methodology):
     • Ask the user: "Please send me these PDF URLs so I can extract their content:"
     • List each PDF URL on a separate line
     • Wait for user to send the URLs (they will auto-extract)
     • Proceed to Phase 3B
   • If PDFs are SUPPLEMENTARY (additional reference, not essential):
     • Note them for future reference
     • Proceed directly to Phase 4 with current documentation

3. If no PDFs listed:

   • Skip to Phase 4 (documentation complete)

Phase 3B: PDF Extraction & Complete Documentation (Only if CRITICAL PDFs found)

1. After receiving extracted PDF content from user:
2. Relaunch @complete:country-models:document-collector agent with:
   • Original task description
   • Extracted PDF content included in prompt
   • Instruction: "You are in Phase 2 - integrate this PDF content with your HTML research"
3. Agent creates complete documentation

Quality Gate: Documentation must include:

• Official program guidelines or state plan
• Income limits and benefit schedules
• Eligibility criteria and priority groups
• Seasonal/temporal rules if applicable
• ✅ All critical PDFs extracted and integrated (if applicable)

Phase 4: Development (Parallel on Same Branch)

Run both agents IN PARALLEL - they work on different folders so no conflicts:

@complete:country-models:test-creator → works in tests/ folder:

• Create comprehensive INTEGRATION tests from documentation
• Create UNIT tests for each variable that will have a formula
• Both test types created in ONE invocation
• Use only existing PolicyEngine variables
• Test realistic calculations based on documentation

@complete:country-models:rules-engineer → works in variables/ + parameters/ folders:

• Implementation Approach: [Pass the decision from Phase 0: "simplified" or "full"]
  • If Simplified TANF: Do NOT create state-specific gross income variables - use federal baseline (tanf_gross_earned_income, tanf_gross_unearned_income)
  • If Full TANF: Create complete state-specific income definitions as needed
• Step 1: Create all parameters first using embedded parameter-architect patterns
  • Complete parameter structure with all thresholds, amounts, rates
  • Include proper references from documentation
• Step 2: Implement variables using the parameters
  • Zero hard-coded values
  • Complete implementations only
  • Follow simplified/full approach from Phase 0

Quality Requirements:

• rules-engineer: ZERO hard-coded values, parameters created before variables
• test-creator: All tests (unit + integration) created together, based purely on documentation

Phase 5: Pre-Push Validation

Invoke @complete:country-models:pr-pusher agent to:

• Ensure changelog entry exists
• Run formatters (black, isort)
• Fix any linting issues
• Run local tests for quick validation
• Push branch and report initial CI status

Quality Gate: Branch must be properly formatted with changelog before continuing.

Optional Enhancement Phases

These phases are OPTIONAL and should be considered based on implementation type:

For Production-Ready Implementations:

The following enhancements may be applied to ensure production quality:

1. Cross-Program Validation

   • @complete:country-models:cross-program-validator: Check interactions with other benefits
   • Prevents benefit cliffs and unintended interactions

2. Documentation Enhancement

   • @complete:country-models:documentation-enricher: Add examples and regulatory citations
   • Improves maintainability and compliance verification

3. Performance Optimization

   • @complete:country-models:performance-optimizer: Vectorize and optimize calculations
   • Ensures scalability for large-scale simulations

Decision Criteria:

• Simplified/Experimental TANF: Skip these optional phases
• Production TANF: Include based on specific requirements
• Full Production Deployment: Include all enhancements

Phase 6: Validation

Run validators to check implementation quality:

@complete:country-models:implementation-validator:

• Check for hard-coded values in variables
• Verify placeholder or incomplete implementations
• Check federal/state parameter organization
• Assess test quality and coverage
• Identify performance and vectorization issues

For TANF/Benefit Programs, also run @complete:country-models:tanf-program-reviewer:

• Learn from PA TANF and OH OWF reference implementations first
• Validate code formulas against regulations
• Verify test coverage with manual calculations
• Check parameter structure and references
• Focus on: eligibility rules, income disregards, benefit formulas

Quality Gate: Review validator reports before proceeding

Phase 7: Local Testing & Fixes

CRITICAL: ALWAYS invoke @complete:country-models:ci-fixer agent - do NOT manually fix issues

Invoke @complete:country-models:ci-fixer agent to:

• Run all tests locally: policyengine-core test policyengine_us/tests/policy/baseline/gov/states/[STATE]/[PROGRAM] -c policyengine_us -v
• Identify ALL failing tests
• For each failing test:
  • Read the test file to understand expected values
  • Read the actual test output to see what was calculated
  • Determine root cause: incorrect test expectations OR bug in implementation
  • Fix the issue:
    • If test expectations are wrong: update the test file with correct values
    • If implementation is wrong: fix the variable/parameter code
  • Re-run tests to verify fix
• Iterate until ALL tests pass locally
• Reference Verification
  • Verify all parameters have reference metadata
  • Verify all variables have reference fields
  • Keep sources/ folder files for future reference
  • If references missing: Create todos for adding them
• Run make format before committing fixes
• Push final fixes to PR branch

Success Metrics:

• All tests pass locally (green output)
• All references embedded in code metadata
• sources/ folder kept for future reference
• Code properly formatted
• Implementation complete and working
• Clean commit history

Phase 8: Final Summary

After all tests pass and references are embedded:

• Update PR description with final implementation status
• Add summary of what was implemented
• Report completion to user
• Keep PR as draft - user will mark ready when they choose
• WORKFLOW COMPLETE

Anti-Patterns This Workflow Prevents

1. Hard-coded values: Rules-engineer enforces parameterization
2. Incomplete implementations: Validator catches before PR
3. Federal/state mixing: Proper parameter organization enforced
4. Non-existent variables in tests: Test creator uses only real variables
5. Missing edge cases: Edge-case-generator covers all boundaries
6. Benefit cliffs: Cross-program-validator identifies interactions
7. Poor documentation: Documentation-enricher adds examples
8. Performance issues: Performance-optimizer ensures vectorization
9. Review delays: Most issues caught and fixed automatically

Execution Instructions

YOUR ROLE: You are an orchestrator ONLY. You must:

1. Invoke agents using the Task tool
2. Wait for their completion
3. Check quality gates
4. PAUSE and wait for user confirmation before proceeding to next phase

YOU MUST NOT:

• Write any code yourself
• Fix any issues manually
• Run tests directly
• Edit files

Execution Flow (ONE PHASE AT A TIME):

Execute each phase sequentially and STOP after each phase to wait for user instructions:

0. Phase 0: Implementation Approach (TANF Programs Only)

   • Auto-detect from $ARGUMENTS ("simple"/"simplified" vs. "full"/"complete")
   • Default to Simplified if unclear
   • Inform user of detected approach
   • STOP - Wait for user to say "continue" or provide adjustments

1. Phase 1: Issue and PR Setup

   • Complete the phase
   • Report results
   • STOP - Wait for user to say "continue" or provide adjustments

2. Phase 2: Variable Naming Convention

   • Complete the phase
   • Report results
   • STOP - Wait for user to say "continue" or provide adjustments

3. Phase 3: Document Collection

   • Complete the phase
   • Report results
   • STOP - Wait for user to say "continue" or provide adjustments

4. Phase 4: Development (Test + Implementation)

   • Pass simplified/full decision to rules-engineer
   • Run test-creator and rules-engineer in parallel (different folders)
   • Report results
   • STOP - Wait for user to say "continue" or provide adjustments

5. Phase 5: Pre-Push Validation

   • Complete the phase
   • Report results
   • STOP - Wait for user to say "continue" or provide adjustments

6. Phase 6: Validation

   • Run validators
   • Report results
   • STOP - Wait for user to say "continue" or provide adjustments

7. Phase 7: Local Testing & Fixes (Including Reference Verification)

   • Complete the phase
   • Report results
   • STOP - Wait for user to say "continue" or provide adjustments

8. Phase 8: Final Summary

   • Update PR description
   • Report final results (keep PR as draft)
   • WORKFLOW COMPLETE

CRITICAL RULES:

• Do NOT proceed to the next phase until user explicitly says to continue
• After each phase, summarize what was accomplished
• If user provides adjustments, incorporate them before continuing
• All 8 phases are REQUIRED - pausing doesn't mean skipping

If any agent fails, report the failure but DO NOT attempt to fix it yourself. Wait for user instructions.