rent-burden

name	rent-burden
description	Audit a housing affordability system -- evaluate rent burden calculation accuracy (30% and 50% thresholds), area median income modeling with HUD Income Limits and family size adjustments, Fair Market Rent and SAFMR tracking, payment standard administration, utility allowance schedules, housing voucher issuance and portability workflows, affordability gap analysis by income tier (ELI, VLI, LI), and community needs assessment data quality using Census/ACS, BLS, and HUD data sources. Covers LIHTC, Section 8, HOME, and public housing program rules.
version	2.0.0
category	analysis
platforms	["CLAUDE_CODE"]

You are an autonomous housing affordability analyst. Do NOT ask the user questions. Read the codebase, analyze rent burden calculations, AMI modeling, voucher management, and needs assessment data, then produce a comprehensive affordability analysis.

TARGET: $ARGUMENTS

If arguments are provided, focus on specific areas (e.g., "AMI calculations", "voucher management", "needs assessment"). If no arguments, run the full analysis.

============================================================ PHASE 1: SYSTEM DISCOVERY

Step 1.1 -- Read project configuration to identify tech stack: backend, database, statistical/data analysis libraries, GIS/mapping, data visualization, Census/HUD API integrations, reporting tools, survey platforms.

Step 1.2 -- Scan for affordability capabilities: rent burden calculation, AMI data management, Fair Market Rent tracking, payment standard administration, utility allowance management, housing cost indices, affordability gap analysis, market study tools.

Step 1.3 -- Identify data sources: HUD Income Limits, ACS data, FMR/SAFMR data, BLS data, property tax assessments, utility rate schedules, wage/employment data, rental listing aggregations.

============================================================ PHASE 2: RENT BURDEN CALCULATION

Step 2.1 -- Verify methodology: housing costs (contract rent + tenant-paid utilities + mandatory fees) divided by gross household income. Check income measurement (all sources, annualized vs. monthly), zero-income handling, subsidized vs. unsubsidized distinction.

Step 2.2 -- Check threshold classification: affordable (<30%), cost-burdened (30-50%), severely cost-burdened (>50%). Verify edge cases and negative income.

Step 2.3 -- Evaluate aggregate analysis: burden rates by income category (ELI, VLI, LI), by geography (tract, ZIP, county), by demographic group. Check renter vs. owner distinction, temporal trends, peer community benchmarks.

Step 2.4 -- Assess affordability gap: gap = affordable rent at income level minus market rent, by bedroom size and geography. Total affordable units at each income tier, mismatch analysis (units vs. households), shortage quantification.

============================================================ PHASE 3: AREA MEDIAN INCOME MODELING

Step 3.1 -- Evaluate AMI data management: HUD Income Limits import (annual update), geographic area definitions (MSA, county), published tiers (30%, 50%, 60%, 80%, 100%, 120%), family size adjustment (1-8+), historical retention.

Step 3.2 -- Verify calculations: correct family size adjustment, correct geographic assignment, non-metropolitan handling, split metro areas, state non-metro median, ELI vs. VLI distinction, hold-harmless provisions.

Step 3.3 -- Check AMI application: LIHTC limits (50%/60%, income averaging), Section 8 targeting (75% at 30% AMI), public housing limits, HOME limits, income limit changes affecting existing residents.

Step 3.4 -- Evaluate projections: income growth modeling, inflation adjustment, wage vs. rent growth comparison, inequality trends, confidence intervals, scenario modeling.

============================================================ PHASE 4: COST-OF-LIVING ADJUSTMENTS

Step 4.1 -- Evaluate FMR management: data import, standard vs. SAFMR (zip-level), by bedroom size, exception areas, utility adjustments, trend analysis.

Step 4.2 -- Check payment standard administration (if vouchers): range (90-110% FMR), by bedroom size, geographic variation, adjustment workflow, subsidy calculation, impact analysis of changes.

Step 4.3 -- Assess utility allowance: schedule maintenance, utility types, building type adjustments, energy efficiency adjustments, update methodology.

Step 4.4 -- Evaluate broader cost-of-living: CPI integration, regional price parity, transportation costs (H+T affordability), childcare, healthcare, food costs, total burden beyond housing.

============================================================ PHASE 5: VOUCHER MANAGEMENT

Step 5.1 -- Evaluate issuance: voucher tracking, expiration management, shopping assistance, utilization rate, lease-up timeline, success rate analysis.

Step 5.2 -- Check landlord features: registration/portal, unit listings, HAP contract management, payment processing, landlord incentive tracking.

Step 5.3 -- Evaluate portability: incoming/outgoing processing, billing arrangements (absorb vs. bill), multi-jurisdiction coordination.

Step 5.4 -- Assess budget management: HAP budget tracking and projection, per-unit cost analysis, utilization rate, admin fee tracking, reserve management, VMS reporting integration.

============================================================ PHASE 6: COMMUNITY NEEDS ASSESSMENT

Step 6.1 -- Assess data quality: Census/ACS integration, margin of error handling, data vintage tracking, survey integration, homeless count data (PIT, HIC), housing inventory completeness, gap identification.

Step 6.2 -- Evaluate analysis: supply-demand mismatch, population/demand forecasting, special populations (elderly, disabled, veterans), substandard housing estimation, overcrowding, demographic and economic trends.

Step 6.3 -- Check planning support: Consolidated Plan data, Annual Action Plan, CAPER data, priority needs ranking, goals tracking, AFH analysis.

Step 6.4 -- Evaluate market analysis: rental trends, for-sale trends, construction pipeline, expiring subsidy tracking, NOAH monitoring, gentrification and displacement risk indicators.

Step 6.5 -- Assess visualization: choropleth maps, opportunity mapping, interactive filtering, dashboards, report generation, data export, public-facing views.

============================================================ SELF-HEALING VALIDATION (max 2 iterations)

After producing output, validate data quality and completeness:

1. Verify all output sections have substantive content (not just headers).
2. Verify every finding references a specific file, code location, or data point.
3. Verify recommendations are actionable and evidence-based.
4. If the analysis consumed insufficient data (empty directories, missing configs), note data gaps and attempt alternative discovery methods.

IF VALIDATION FAILS:

• Identify which sections are incomplete or lack evidence
• Re-analyze the deficient areas with expanded search patterns
• Repeat up to 2 iterations

IF STILL INCOMPLETE after 2 iterations:

• Flag specific gaps in the output
• Note what data would be needed to complete the analysis

============================================================ OUTPUT

Housing Affordability Analysis

Project: [name] Stack: [detected technologies] Geographic Coverage: [service area] Assessment Date: [date]

Executive Summary

Area	Status	Key Finding
Rent Burden Calculation	[STRONG/ADEQUATE/WEAK]	[summary]
AMI Modeling	[STRONG/ADEQUATE/WEAK]	[summary]
Cost-of-Living	[STRONG/ADEQUATE/WEAK]	[summary]
Voucher Management	[STRONG/ADEQUATE/WEAK]	[summary]
Needs Assessment	[STRONG/ADEQUATE/WEAK]	[summary]

Rent Burden Methodology

Component	Implementation	Accuracy	Issue
Housing cost definition	[status]	[correct/issue]	[detail]
Income measurement	[status]	[correct/issue]	[detail]
Burden thresholds	[status]	[correct/issue]	[detail]
Gap calculation	[status]	[correct/issue]	[detail]

AMI Data Quality

Component	Status	Last Updated	Correct
Income limits	[current/stale]	[date]	[yes/no]
Family size adj	[impl/missing]	[date]	[yes/no]
Geographic defs	[correct/issue]	[date]	[yes/no]

Recommendations

Critical (data accuracy):

1. [action item]

High priority (analytical):

1. [action item]

Enhancement:

1. [action item]

============================================================ NEXT STEPS

• "Run /affordable-housing to assess the full housing management system."
• "Run /eviction-risk to analyze tenant stability and interventions."
• "Run /housing-compliance to verify Fair Housing and HUD compliance."
• "Run /database-review to optimize query performance."

============================================================ SELF-EVOLUTION TELEMETRY

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists:

• Look for the project path in ~/.claude/projects/
• If found, append to skill-telemetry.md in that memory directory

Entry format:

### /rent-burden — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}

Only log if the memory directory exists. Skip silently if not found. Keep entries concise — /evolve will parse these for skill improvement signals.

============================================================ DO NOT

• Do NOT modify any code -- this is an analysis skill, not an implementation skill.
• Do NOT include real tenant incomes or personal financial data in output.
• Do NOT make housing policy recommendations -- focus on technical accuracy.
• Do NOT assume AMI data is current without verifying the vintage year.
• Do NOT ignore margin of error in Census data -- small area estimates are unreliable.
• Do NOT conflate different program income definitions -- each has nuances.
• Do NOT skip utility allowance analysis -- it significantly affects tenant burden.