--- name: affordable-housing description: > Analyzes affordable housing management software for unit allocation algorithms, waitlist management, income verification workflows, Fair Housing compliance, LIHTC and Section 8 program tracking, inspection scheduling, and tenant reporting. USE THIS SKILL WHEN: - You are reviewing housing management software or tenant management systems - Someone asks about Section 8, LIHTC, or public housing program compliance - You need to audit unit allocation algorithms for fairness or bias - A project involves waitlist management, income verification, or rent calculations - You are evaluating HUD compliance (50058, EIV, PIC submissions) - Someone mentions Fair Housing, reasonable accommodation, or protected class handling - You need to review HQS/NSPIRE inspection tracking or abatement workflows - A codebase handles tenant eligibility, subsidy calculations, or housing vouchers TRIGGER PHRASES: "affordable housing", "Section 8", "LIHTC", "public housing", "waitlist management", "income verification", "Fair Housing", "HUD compliance", "rent calculation", "housing voucher", "tenant management", "HQS inspection", "unit allocation", "housing authority" version: "2.0.0" category: analysis platforms: - CLAUDE_CODE --- 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 | Area | Status | Key Finding | |------|--------|-------------| | Unit Allocation | [STRONG/ADEQUATE/WEAK] | [summary] | | Waitlist | [STRONG/ADEQUATE/WEAK] | [summary] | | Income Verification | [STRONG/ADEQUATE/WEAK] | [summary] | | Fair Housing | [STRONG/ADEQUATE/WEAK] | [summary] | | LIHTC Compliance | [STRONG/ADEQUATE/WEAK] | [summary] | | Section 8 | [STRONG/ADEQUATE/WEAK] | [summary] | | Tenant Reporting | [STRONG/ADEQUATE/WEAK] | [summary] | ### Allocation Algorithm | Component | Method | Configurable | Auditable | Fair Housing Safe | |-----------|--------|-------------|-----------|-------------------| | Priority scoring | [method] | [yes/no] | [yes/no] | [yes/no] | | Unit matching | [method] | [yes/no] | [yes/no] | [yes/no] | ### Income Calculation Audit | Component | Status | Finding | |-----------|--------|---------| | Part 5 income | [CORRECT/ISSUE] | [detail] | | Asset income | [CORRECT/ISSUE] | [detail] | | Utility allowance | [CORRECT/ISSUE] | [detail] | | Rent calculation | [CORRECT/ISSUE] | [detail] | ### 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.