217 added, 70 removed. Audit A to A.
---
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, inspections scheduling, and tenant reporting.
+ 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: "1.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 -- Read project configuration to identify tech stack: backend framework,
- database, frontend, document management, reporting tools, GIS/mapping, payment
- processing, external API integrations (HUD systems, credit bureaus).
+ Step 1.1 -- Tech Stack Detection
- Step 1.2 -- Scan for supported housing programs: 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. Record eligibility criteria, subsidy calculations,
- reporting requirements for each.
+ 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.3 -- Map the property/unit data model: property records, unit records
- (bedrooms, sqft, accessibility features), unit status tracking, amenities,
- utility configurations, ADA unit cataloging.
+ 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
+ PHASE 2: UNIT ALLOCATION ALGORITHM AUDIT
============================================================
- Step 2.1 -- Evaluate priority/preference system: federal preferences (displacement,
- homelessness, rent burden), local preferences (residency, veterans, elderly),
- point calculations, preference verification, tie-breaking rules, date-and-time
- vs. lottery selection.
+ Step 2.1 -- Priority/Preference System
- Step 2.2 -- Analyze unit matching: bedroom size determination (subsidy standards),
- accessibility matching, income targeting (ELI, VLI, LI bands), LIHTC set-aside
- compliance, reasonable accommodation handling, transfer vs. new admission
- priority, over/under-housed transfer logic.
+ 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
- Step 2.3 -- Assess fairness: consistent preference application, no manual override
- without audit trail, equal treatment across protected classes, lottery integrity,
- geographic deconcentration, AFFH alignment.
+ 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 -- Evaluate design: site-based vs. centralized, program-specific vs.
- merged, open/close management, size controls, wait time estimation, position
- tracking and notification.
+ Step 3.1 -- Waitlist Design
- Step 3.2 -- Check maintenance: purge notification process, response tracking,
- status updates, contact info changes, preference re-verification, merge and
- reorganization tools.
+ 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.3 -- Evaluate application processing: receipt and date-stamping,
- preliminary screening, full determination, document checklist, interview
- scheduling, voucher issuance, unit offer tracking, lease-up timeline, denial
- and informal hearing process.
+ 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 -- Verify income calculation accuracy: Part 5 annual income definition
- (24 CFR 5.609), inclusions and exclusions, asset income (actual vs. imputed),
- net family assets, self-employment, irregular income, child support, welfare.
+ Step 4.1 -- Income Calculation Accuracy
- Step 4.2 -- Check HUD verification hierarchy: Level 1 UIV/EIV, Level 2 written
- third-party, Level 3 oral third-party, Level 4 self-certification. Verify
- 120-day lookback and document retention.
+ 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.3 -- Assess EIV integration: data import, income discrepancy identification,
- identity verification, deceased alerts, immigration alerts, multiple subsidy
- detection.
+ Step 4.2 -- HUD Verification Hierarchy
- Step 4.4 -- Verify rent calculation: Total Tenant Payment (30% adjusted monthly
- income), minimum rent and hardship exemption, flat vs. income-based rent,
- utility allowance, ceiling rent, payment standard (Section 8), HAP determination.
+ 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 -- Check protected class handling: data collected for reporting only
- (not screening), no protected class visibility in allocation decisions, no
- discriminatory filtering, equal opportunity marketing.
+ Step 5.1 -- Protected Class Handling
- Step 5.2 -- Check reasonable accommodation: request intake, interactive process,
- approval/denial workflow, modification tracking, service/support animal tracking,
- appeal process.
+ 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.3 -- Evaluate LIHTC compliance: minimum set-aside tracking (20-50, 40-60,
- income averaging), applicable fraction, student rule, good cause eviction,
- recertification, available unit rule, extended use period, state HFA reporting.
+ Step 5.2 -- Reasonable Accommodation
- Step 5.4 -- Check Section 8 compliance: HQS/NSPIRE inspection tracking, rent
- reasonableness, payment standard administration, portability processing,
- reexamination scheduling, FSS tracking, SEMAP indicators.
+ 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.5 -- Evaluate inspection management: scheduling (annual, move-in, special),
- deficiency tracking, emergency vs. non-emergency failures, abatement tracking,
- life-threatening escalation (24-hour requirement), property condition trending.
+ 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
+ PHASE 6: TENANT REPORTING AND COMMUNICATION
============================================================
- Step 6.1 -- Check regulatory reporting: HUD-50058 generation and PIC submission,
- VMS reporting, FASS financial reporting, civil rights data, LIHTC 8823 generation.
+ Step 6.1 -- Regulatory Reporting
- Step 6.2 -- Evaluate tenant communication: notice generation (rent changes, lease
- violations, termination), timing compliance, recertification reminders, tenant
- portal, language-appropriate notices.
+ 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.3 -- Assess outcome tracking: length of stay, income progression, move-out
- reasons, positive exits, program violations, grievance process tracking.
+ 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
+
============================================================
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]
+ 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."
============================================================
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.