Clarity Engine — VA Loan Module Skill

Version: 1.0 | Status: Implementation-Ready — Gear 1

Table of Contents SKILL PURPOSE SOURCE HIERARCHY INVOCATION FORMAT EXECUTION SEQUENCE OUTPUT FORMAT NOVA EXPLANATION RULES IMPLEMENTATION GUARDRAILS VERIFIED TEST CASES SCOPE BOUNDARIES

Clarity Engine — VA Loan Module Skill

Version: 1.0 | Status: Implementation-Ready — Gear 1

Authority: VA Pamphlet 26-7 / VA.gov official guidance

Scope: Base VA underwriting rules only. Does not replace AUS, lender overlays, or COE workflow.

Confidential: PreFi, Inc. / Purpose Technology, Inc. d/b/a Purlend

SKILL PURPOSE

When invoked, this skill evaluates a VA loan scenario against official VA underwriting rules. It computes:

Eligibility (COE, service, occupancy)
Entitlement (full vs. partial, down payment required)
Loan purpose routing (purchase / IRRRL / cash-out)
Residual income (shelter expense, actual vs. required, 120% rule)
Funding fee (exemption, purpose/use/tier lookup, financed total)
Closing cost / seller concession validation
Income handler (gross/net distinction, tax-free gross-up rule)

Output includes: pass/fail for each object, all computed values, explanation text suitable for Nova, and rule citations for every result.

SOURCE HIERARCHY

Tier	Source	Role
1	VA.gov Eligibility (SRC-VA-ELIG)	COE, service, occupancy
1	VA Chapter 4 Credit Underwriting (SRC-VA-CH4)	Residual income, DTI, 120% rule
1	VA Funding Fee Page (SRC-VA-FEE)	Fee tables, closing cost rules
1	VA Loan Limits Page (SRC-VA-LIMITS)	Entitlement
1	VA Cash-Out Page (SRC-VA-CASHOUT)	Cash-out occupancy, Type I/II
1	VA IRRRL Page (SRC-VA-IRRRL)	IRRRL restrictions
2	Ginnie Mae MBS Guide	SECURITIZATION ONLY — never applied to borrower underwriting
3	Lender Overlays	Separate overlay layer — never mixed into base rules

INVOCATION FORMAT

When a user provides borrower data for VA evaluation, collect the following inputs (ask for any that are missing before computing):


REQUIRED INPUTS:
  coe_status:                    obtained | pending | not_applied
  service_eligibility_status:    eligible | ineligible | pending
  surviving_spouse_flag:         true | false
  occupancy_intent:              primary_residence | second_home | investment
  discharge_type:                honorable | general | other_than_honorable
  va_loan_purpose:               purchase | irrrl | cash_out_type1 | cash_out_type2
  full_entitlement_flag:         true | false
  partial_entitlement_flag:      true | false
  remaining_entitlement_amount:  (if partial)
  base_loan_amount:              decimal
  gross_monthly_income:          decimal  [used for DTI — GROSS]
  net_effective_income:          decimal  [used for residual income — NET]
  monthly_debt_obligations:      decimal
  principal_and_interest:        decimal
  monthly_property_tax:          decimal
  monthly_hazard_insurance:      decimal
  hoa_monthly:                   decimal (0 if none)
  property_sqft:                 integer
  family_size_for_residual_income: integer (1–10+)
  residual_income_region:        Northeast | Midwest | South | West
  funding_fee_exempt_flag:       true | false
  prior_va_use_count:            integer (0 = first use)
  down_payment_percent:          decimal (purchase only)
  funding_fee_financed_flag:     true | false

EXECUTION SEQUENCE

Run these 7 objects in order. Stop at any Hard Gate failure.

OBJECT 1: ELIGIBILITY + COE


VA_ELIG_001: IF coe_status != obtained → conditional_pending_coe (HARD GATE — stop)
VA_ELIG_002: IF service_eligibility_status != eligible AND surviving_spouse_flag = false → ineligible (HARD GATE)
VA_ELIG_003: IF va_loan_purpose = purchase AND occupancy_intent != primary_residence → ineligible (HARD GATE)
VA_ELIG_004: IF va_loan_purpose IN (cash_out_type1, cash_out_type2) AND occupancy_intent != primary_residence → ineligible (HARD GATE)
VA_ELIG_005: IF discharge_type = other_than_honorable → flag_for_human_review (REVIEW_REQUIRED)

NOTE: IRRRL uses PRIOR occupancy certification — do NOT apply VA_ELIG_003 to IRRRL.

OBJECT 2: ENTITLEMENT


VA_ENT_001: IF full_entitlement_flag = true
  → required_down_payment_amount = 0
  → no loan limit cap applies

VA_ENT_002: IF partial_entitlement_flag = true
  → guaranty_available = remaining_entitlement_amount × 4
  → IF base_loan_amount > guaranty_available:
       required_down_payment_amount = (base_loan_amount - guaranty_available) × 0.25
  → ELSE: required_down_payment_amount = 0

OBJECT 3: LOAN PURPOSE ROUTER


purchase        → Full underwriting. Residual income required. Appraisal required. Primary occupancy.
irrrl           → Skip residual income, income verification, credit, appraisal (standard).
                  VA-to-VA only. No cash out. Fee = 0.50% flat.
cash_out_type1  → Full underwriting. Existing VA loan. No net cash. Borrower must occupy.
cash_out_type2  → Full underwriting. Any loan type to VA. Cash allowed. Borrower must occupy.

VA_PURPOSE_001: IF irrrl AND cash_out_requested > 0 → ineligible (HARD GATE)
VA_PURPOSE_002: IF irrrl AND existing_loan_family != VA → ineligible (HARD GATE)

OBJECT 4: RESIDUAL INCOME ENGINE

CRITICAL: Two income variables — never one.

gross_monthly_income → DTI denominator (gross-up applies for tax-free income)
net_effective_income → Residual income formula (NO gross-up)

Step 1: Maintenance & Utilities Allowance


maintenance_utilities_allowance = property_sqft × 0.14

Step 2: Monthly Shelter Expense


monthly_shelter_expense = principal_and_interest
                        + monthly_property_tax
                        + monthly_hazard_insurance
                        + hoa_monthly
                        + maintenance_utilities_allowance

Step 3: DTI Ratio (GROSS income)


dti_ratio = (monthly_shelter_expense + monthly_debt_obligations) / gross_monthly_income
dti_over_41_flag = (dti_ratio > 0.41)

Step 4: Actual Residual Income (NET income)


actual_residual_income = net_effective_income
                       - monthly_shelter_expense
                       - monthly_debt_obligations

Step 5: Required Residual Income (lookup)


bucket = "80k+" if base_loan_amount >= 80000 else "Under80k"
family_cap = min(family_size_for_residual_income, 5)
required_residual_income = RESIDUAL_TABLE[bucket][family_cap][residual_income_region]
if family_size > 5:
  required_residual_income += (family_size - 5) × ADD_ON[bucket]

Residual Income Lookup Tables:

Table A — Loans $80,000 and Above (80k+ bucket):

Family	Northeast	Midwest	South	West
1	$450	$441	$441	$491
2	$755	$738	$738	$823
3	$909	$889	$889	$990
4	$1,025	$1,003	$1,003	$1,117
5	$1,062	$1,039	$1,039	$1,158
+6 each	+$80	+$80	+$80	+$80

Table B — Loans Below $80,000 (Under80k bucket):

Family	Northeast	Midwest	South	West
1	$390	$382	$382	$425
2	$654	$641	$641	$713
3	$788	$772	$772	$859
4	$888	$868	$868	$967
5	$921	$902	$902	$1,004
+6 each	+$75	+$75	+$75	+$75

Source: VA Pamphlet 26-7, Chapter 4 (SRC-VA-CH4)

Step 6: Pass / Fail


VA_DTI_001: IF dti_ratio <= 0.41 → threshold = required_residual_income
VA_DTI_002: IF dti_ratio > 0.41  → threshold = required_residual_income × 1.20 (120% rule)

residual_income_pass = (actual_residual_income >= threshold)
IF NOT residual_income_pass → human_review_required = true (not auto-decline)

OBJECT 5: FUNDING FEE CALCULATOR

Run exemption check FIRST.

Exemption conditions (fee = $0 if any apply):

Service-connected disability rating ≥ 10%
Surviving spouse receiving DIC
Active duty Purple Heart recipient (post Jan 1, 2020)

Fee Matrix (effective April 7, 2023):

Purpose	Use Type	Down Payment	Fee %
Purchase	First use	< 5%	2.15%
Purchase	First use	5% to < 10%	1.50%
Purchase	First use	≥ 10%	1.25%
Purchase	Subsequent	< 5%	3.30%
Purchase	Subsequent	5% to < 10%	1.50%
Purchase	Subsequent	≥ 10%	1.25%
Cash-Out	First use	N/A	2.15%
Cash-Out	Subsequent	N/A	3.30%
IRRRL	Any	N/A	0.50%

Source: SRC-VA-FEE

Calculation rules:


VA_FF_001: IF exempt → fee = 0, STOP
VA_FF_002: IF irrrl → fee_pct = 0.005
VA_FF_003: IF cash_out → fee_pct = 0.0215 if first use, 0.033 if subsequent
VA_FF_004: IF purchase → lookup by (prior_va_use_count, down_payment_percent)
VA_FF_005: funding_fee_amount = base_loan_amount × funding_fee_percent
VA_FF_006: IF financed → total_loan_amount = base_loan_amount + funding_fee_amount
            THEN recalculate LTV and monthly P&I
           ELSE total_loan_amount = base_loan_amount

OBJECT 6: CLOSING COST VALIDATOR


VA_CTC_001: Purchase only — only the VA funding fee may be financed into the loan.
            All other fees (origination, title, appraisal, prepaid) must be paid at closing.

VA_SELL_001: seller_concessions must not exceed 4% of reasonable value.
             "Seller concessions" ≠ "closing costs"
             Standard closing costs (origination, title, appraisal) are NOT subject to the 4% cap.
             The 4% cap covers: seller-paid prepaid items, discount points above 2, funding fee if seller pays.

OBJECT 7: INCOME HANDLER


VA_INC_001: Include only income that is stable, documented, and expected to continue.

VA_INC_002: IF income_stream = tax_free:
  → gross_up applies to DTI calculation (increases gross_monthly_income denominator)
  → gross_up does NOT apply to residual income (use actual net amount)
  → This produces different DTI and residual income values from the same income stream.
     Both must be computed separately.

OUTPUT FORMAT

When computing a VA evaluation, present results in this structure:


VA LOAN EVALUATION — [BORROWER NAME / SCENARIO ID]
Date: [Date]
Source: Clarity Engine VA Module v1.0

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
OBJECT 1: ELIGIBILITY + COE
  COE Status:              [value] → [PASS / CONDITIONAL_PENDING / HARD_GATE]
  Service Eligibility:     [value] → [PASS / HARD_GATE]
  Occupancy:               [value] → [PASS / HARD_GATE]
  Eligibility Result:      [PASS / INELIGIBLE / CONDITIONAL]

OBJECT 2: ENTITLEMENT
  Entitlement Type:        [Full / Partial]
  Down Payment Required:   $[amount]

OBJECT 3: LOAN PURPOSE
  Purpose:                 [value]
  Rule Tree:               [PURCHASE_RULES / IRRRL_RULES / CASHOUT_T1 / CASHOUT_T2]
  IRRRL Bypass Applied:    [Yes / No]

OBJECT 4: RESIDUAL INCOME
  Maintenance Allowance:   $[sqft × 0.14]
  Monthly Shelter Expense: $[computed]
  DTI Ratio:               [X.X%] → [At/Below 41% / Over 41% — 120% rule applies]
  Required Residual:       $[lookup] (Family [N], [Region], [bucket])
  120% Threshold:          $[required × 1.20] (if DTI > 41%)
  Actual Residual:         $[net - shelter - debt]
  Residual Income Result:  [PASS / HUMAN_REVIEW_REQUIRED]

OBJECT 5: FUNDING FEE
  Exempt:                  [Yes / No]
  Fee Rate:                [X.XX%]
  Fee Amount:              $[base × rate]
  Total Loan Amount:       $[base + fee if financed]

OBJECT 6: CLOSING COSTS
  Financing Limit:         Funding fee only
  Seller Concession Cap:   4% of reasonable value = $[amount]

OBJECT 7: INCOME
  Gross Monthly Income:    $[value] [gross-up applied if tax-free income present]
  Net Effective Income:    $[value]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
FINAL RESULT: [PASS / INELIGIBLE / CONDITIONAL_PENDING / HUMAN_REVIEW_REQUIRED]

NOVA EXPLANATION (Borrower-Facing):
"[Generated explanation — see Nova rules below]"

RULE CITATIONS:
  [List each rule applied with source ID]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

NOVA EXPLANATION RULES

When generating borrower-facing explanation text:

Never state or imply approval. Use: "Based on the information provided, you appear to qualify..." Never: "You are approved."

Cite the VA standard for residual income. Example: "VA requires that after your housing costs and monthly debts, you have at least $[X] remaining each month to support your household of [N] in the [Region] region. Your actual remaining amount is $[Y], which [meets / exceeds] that requirement."

Explain the 120% rule clearly when it applies. Example: "Your debt-to-income ratio of [X%] exceeds VA's 41% benchmark. When this occurs, VA requires your remaining monthly income to be at least 20% above the standard guideline — in your case, $[threshold] rather than $[base_required]. Your actual remaining income of $[actual] [meets / does not meet] that higher threshold."

State funding fee and exemption clearly. Example: "As a first-time VA loan user with no down payment, your VA funding fee is 2.15% of the loan amount, or $[amount]. This can be financed into your loan, bringing your total loan amount to $[total]." For exempt borrowers: "As a veteran with a service-connected disability rating, your VA funding fee is waived."

Never cite Ginnie Mae as a source for borrower qualification decisions.

Always append required disclosure: "This evaluation is based on the inputs provided and official VA underwriting guidelines. It is not a loan approval, commitment to lend, or replacement for a formal underwriting decision by a licensed lender."

IMPLEMENTATION GUARDRAILS

The following must never occur when using this skill:

Prohibited Action	Reason
Applying Fannie Mae DTI limits to VA loans	VA uses residual income as primary test, not DTI hard stops
Using one income variable for both DTI and residual	Gross vs. net produce different numbers; using one breaks both
Applying gross-up to residual income calculation	Gross-up applies to DTI only
Attributing any VA rule to Ginnie Mae	Ginnie Mae is securitization only
Treating DTI > 41% as an automatic decline	It triggers the 120% residual rule, not a hard stop
Using one rules tree for IRRRL, purchase, and cash-out	Each purpose has incompatible rules
Applying current occupancy test to IRRRL	IRRRL uses prior occupancy certification
Including lender overlays in base VA computation	Overlays are a separate layer
Using 80k+ table for all loans	Under80k bucket uses different (lower) values
Applying the 4% concession cap to all closing costs	Cap applies to seller concessions only, not standard closing costs

VERIFIED TEST CASES

Use these to validate implementation correctness:

TC	Purpose	Gross	Net	Debt	Shelter	DTI	Req Resid	Act Resid	Threshold	FF%	Total Loan	Result
TC01	Purchase, 1st, 0% dn	$9,000	$7,000	$700	$3,150	42.8%	$1,117	$3,150	$1,340	2.15%	$408,600	PASS
TC02	Purchase, Subs, 0% dn	$9,000	$7,000	$700	$3,150	42.8%	$1,117	$3,150	$1,340	3.30%	$413,200	PASS
TC03	Purchase, 1st, 10% dn	$8,500	$6,500	$600	$2,720	39.1%	$889	$3,180	$889	1.25%	$354,375	PASS
TC04	Cash-Out, 1st	$10,000	$7,600	$1,200	$2,990	41.9%	$738	$3,410	$886	2.15%	$306,450	PASS
TC05	Cash-Out, Subs	$10,000	$7,600	$1,200	$2,990	41.9%	$738	$3,410	$886	3.30%	$309,900	PASS
TC06	IRRRL	$8,000	$6,300	$500	$2,520	37.8%	$823	$3,280	$823	0.50%	$251,250	PASS
TC07	Purchase, Exempt	$9,200	$7,100	$650	$3,290	42.8%	$1,117	$3,160	$1,340	0.00%	$425,000	PASS
TC08	High DTI, 120% borderline	$7,000	$5,000	$900	$2,860	53.7%	$1,003	$1,240	$1,204	2.15%	$357,525	PASS ✓
TC09	High DTI, 120% clear	$7,000	$6,500	$900	$2,860	53.7%	$1,003	$2,740	$1,204	2.15%	$357,525	PASS
TC10	Investment occupancy	$8,000	$6,200	$700	$2,590	41.1%	$990	$2,910	$1,188	2.15%	—	INELIGIBLE

TC08 Note: Workbook Expected_Result column labels TC08 as "Fail 120% rule." This is a labeling error. The formula and computed math produce a PASS ($1,240 >= $1,204). Implement per the math, not the label.

SCOPE BOUNDARIES

This skill DOES:

Evaluate VA eligibility, entitlement, loan purpose, residual income, funding fee, closing costs, income treatment
Compute all derived fields and apply all rules per official VA guidance
Generate Nova-style borrower-facing explanations with proper disclaimers
Cite rules and sources for every decision

This skill DOES NOT:

Replace AUS / DU / LP findings
Apply lender overlays (that is a separate overlay skill)
Execute Ginnie Mae securitization logic (separate module)
Make final credit decisions
Guarantee loan approval
Handle full partial entitlement production workflow (requires COE data integration)
Apply credit score underwriting policy (lender-specific overlay)