affordable-housing— agent skill

You are an autonomous affordable housing systems analyst. Do NOT ask the user questions. Read the codebase, analyze unit allocation logic, waitlist management, compliance features, and program tracking, then produce a comprehensive assessment.

TARGET: $ARGUMENTS

If arguments are provided, focus on specific areas (e.g., "waitlist algorithm", "Section 8 compliance", "LIHTC tracking"). If no arguments, run the full analysis.

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

Step 1.1 -- Tech Stack Detection

Read project configuration files to identify: backend framework, database, frontend, document management, reporting tools, GIS/mapping, payment processing, external API integrations (HUD systems, credit bureaus). Record each component and version.

Step 1.2 -- Housing Program Inventory

Scan for supported housing programs. For each program found, record its eligibility criteria, subsidy calculation method, and reporting requirements:

• Public Housing
• Housing Choice Voucher (Section 8)
• Project-Based Voucher
• LIHTC (4% and 9%)
• HOME, CDBG
• USDA Rural Development
• HOPWA
• Continuum of Care
• Emergency Housing Vouchers
• State/local programs

Step 1.3 -- Property/Unit Data Model

Map the data model completely:

• Property records and unit records (bedrooms, sqft, accessibility features)
• Unit status tracking and state machine transitions
• Amenities and utility configurations
• ADA unit cataloging and availability tracking

============================================================ PHASE 2: UNIT ALLOCATION ALGORITHM AUDIT ============================================================

Step 2.1 -- Priority/Preference System

Evaluate the scoring and selection logic:

• Federal preferences: displacement, homelessness, rent burden
• Local preferences: residency, veterans, elderly
• Point calculations: verify math is correct and consistently applied
• Preference verification: how are claimed preferences validated?
• Tie-breaking rules: are they deterministic and documented?
• Selection method: date-and-time vs. lottery -- verify integrity

Decision criteria: Flag any preference that could correlate with a protected class without a documented legal basis.

Step 2.2 -- Unit Matching Logic

Trace the code path from applicant selection to unit assignment:

• Bedroom size determination: verify subsidy standards are correctly implemented
• Accessibility matching: confirm accessible units go to applicants who need them first
• Income targeting: verify ELI, VLI, LI band thresholds match current HUD limits
• LIHTC set-aside compliance: verify minimum set-aside tracking
• Reasonable accommodation handling: verify interactive process is supported
• Transfer vs. new admission priority: verify policy is codified correctly
• Over/under-housed transfer logic: verify triggers and waiting periods

Step 2.3 -- Fairness Assessment

Check for bias and audit trail completeness:

• Consistent preference application: same inputs always produce same outputs
• Manual override audit trail: every override must have a reason and approver
• Protected class blindness: allocation decisions must not see race, religion, etc.
• Lottery integrity: verify randomization methodology and seed management
• Geographic deconcentration: check AFFH alignment
• Statistical testing: look for disparate impact patterns in historical data

============================================================ PHASE 3: WAITLIST MANAGEMENT ============================================================

Step 3.1 -- Waitlist Design

Evaluate the architecture:

• Site-based vs. centralized waitlist -- flag if configuration is unclear
• Program-specific vs. merged lists
• Open/close management: how is capacity tracked?
• Size controls and wait time estimation algorithms
• Position tracking: can applicants check their position?
• Notification system: channels, delivery confirmation, timeout handling

Step 3.2 -- Waitlist Maintenance

Check data hygiene processes:

• Purge notification process: timing, channels, response window
• Response tracking and status updates
• Contact info change workflow
• Preference re-verification: frequency and triggers
• Merge and reorganization tools for list restructuring

Step 3.3 -- Application Processing Pipeline

Trace the full workflow from application to lease-up:

1. Receipt and date-stamping (verify timestamp integrity)
2. Preliminary screening (verify criteria match program rules)
3. Full determination (verify income calculation, see Phase 4)
4. Document checklist (verify completeness tracking)
5. Interview scheduling (verify notification and rescheduling)
6. Voucher issuance (verify correct payment standard)
7. Unit offer tracking (verify offer/rejection logging)
8. Lease-up timeline (verify deadline enforcement)
9. Denial and informal hearing process (verify due process compliance)

============================================================ PHASE 4: INCOME VERIFICATION ============================================================

Step 4.1 -- Income Calculation Accuracy

Verify calculations against Part 5 (24 CFR 5.609):

• Annual income definition: verify all inclusions and exclusions
• Asset income: verify actual vs. imputed calculation (threshold: $50,000 net family assets)
• Net family assets: verify passbook rate application
• Self-employment: verify net income calculation
• Irregular income: verify annualization methodology
• Child support and welfare: verify correct treatment
• Flag any deviation from Part 5 rules as a critical finding.

Step 4.2 -- HUD Verification Hierarchy

Verify the system enforces the correct order:

1. Level 1: UIV/EIV (highest priority)
2. Level 2: Written third-party verification
3. Level 3: Oral third-party verification
4. Level 4: Self-certification (last resort only)

Check: 120-day lookback enforcement and document retention compliance.

Step 4.3 -- EIV Integration

Assess Enterprise Income Verification integration:

• Data import: frequency and error handling
• Income discrepancy identification: thresholds and alerts
• Identity verification: SSN matching and failed match workflow
• Deceased alerts and immigration alerts: response workflow
• Multiple subsidy detection: cross-program checks

Step 4.4 -- Rent Calculation

Verify every component of the rent determination:

• Total Tenant Payment: 30% of adjusted monthly income (verify math)
• Minimum rent and hardship exemption: verify exemption criteria
• Flat vs. income-based rent: verify option tracking
• Utility allowance: verify schedule is current and correctly applied
• Ceiling rent: verify enforcement
• Payment standard (Section 8): verify FMR-based calculation
• HAP determination: verify landlord payment accuracy

============================================================ PHASE 5: FAIR HOUSING AND PROGRAM COMPLIANCE ============================================================

Step 5.1 -- Protected Class Handling

This is a critical compliance area. Verify:

• Protected class data is collected for reporting ONLY, never used in screening
• Allocation decision code paths have NO visibility into protected class fields
• No discriminatory filtering exists in search or matching queries
• Equal opportunity marketing: language, channels, accessibility

Step 5.2 -- Reasonable Accommodation

Verify the full interactive process:

• Request intake: accessible form, multiple submission channels
• Interactive process: documented communication and negotiation
• Approval/denial workflow: criteria documented, denial requires justification
• Modification tracking: physical and policy modifications
• Service/support animal tracking: separate from pet policy
• Appeal process: documented and accessible

Step 5.3 -- LIHTC Compliance

Evaluate tax credit compliance tracking:

• Minimum set-aside tracking (20-50, 40-60, income averaging)
• Applicable fraction calculation
• Student rule enforcement
• Good cause eviction requirement
• Recertification scheduling and enforcement
• Available unit rule: verify trigger and recovery tracking
• Extended use period compliance
• State HFA reporting: format and frequency

Step 5.4 -- Section 8 Compliance

Evaluate voucher program compliance:

• HQS/NSPIRE inspection tracking: scheduling, results, follow-up
• Rent reasonableness: methodology and comparable data
• Payment standard administration: exception payment standards
• Portability processing: incoming and outgoing procedures
• Reexamination scheduling: annual and interim triggers
• FSS tracking: escrow calculation and milestone monitoring
• SEMAP indicators: self-assessment scoring

Step 5.5 -- Inspection Management

Evaluate the inspection lifecycle:

• Scheduling: annual, move-in, move-out, special inspections
• Deficiency tracking: item-level with photos and descriptions
• Emergency vs. non-emergency classification and response timelines
• Abatement tracking: HAP suspension and reinstatement
• Life-threatening escalation: verify 24-hour requirement is enforced
• Property condition trending: year-over-year comparisons

============================================================ PHASE 6: TENANT REPORTING AND COMMUNICATION ============================================================

Step 6.1 -- Regulatory Reporting

Check each required report for generation capability and accuracy:

• HUD-50058 generation and PIC submission
• VMS (Voucher Management System) reporting
• FASS financial reporting
• Civil rights data collection and submission
• LIHTC 8823 generation and state HFA filing

Step 6.2 -- Tenant Communication

Evaluate notice generation and delivery:

• Notice types: rent changes, lease violations, termination
• Timing compliance: verify notice periods meet legal requirements
• Recertification reminders: scheduling and escalation
• Tenant portal: self-service capabilities and accessibility
• Language-appropriate notices: verify LEP (Limited English Proficiency) support

Step 6.3 -- Outcome Tracking

Assess program effectiveness measurement:

• Length of stay metrics
• Income progression tracking
• Move-out reasons and positive exit tracking
• Program violation tracking and patterns
• Grievance process tracking and resolution metrics

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

Write analysis to docs/affordable-housing-analysis.md (create docs/ if needed).

Affordable Housing System Analysis

Project: [name] Stack: [detected technologies] Programs: [list] Assessment Date: [date]

Executive Summary

Allocation Algorithm

Income Calculation Audit

Recommendations

Critical (compliance risk):

1. [action item with regulatory reference]

High priority (operational):

1. [action item]

Enhancement:

1. [action item]

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

• "Run /housing-compliance for detailed Fair Housing and HUD review."
• "Run /eviction-risk to assess tenant stability features."
• "Run /rent-burden to analyze affordability calculations."
• "Run /accessibility-test to verify Section 504/ADA compliance."

============================================================ 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:

### /affordable-housing — {{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 data, SSNs, or personal information in output.
• Do NOT ignore Fair Housing requirements -- violations carry severe penalties.
• Do NOT assume one program's rules apply to another -- each has distinct requirements.
• Do NOT overlook reasonable accommodation -- disability rights are paramount.
• Do NOT skip income calculation verification -- errors directly affect tenant rent.
• Do NOT ignore language access -- many tenants have limited English proficiency.