Version: 1.0 | Status: Implementation-Ready — Gear 1
Scope: Multi-program optimization engine. Takes all program qualification results (VA, Conventional, FHA, DSCR) and produces a scored, ranked, goal-aligned recommendation with sensitivity analysis and a clear path to the borrower's best outcome.
Confidential: PreFi, Inc. / Purpose Technology, Inc. d/b/a Purlend
The Optimization Skill is the analytical brain of Gate 2. It synthesizes all upstream qual results into a single actionable answer: what is the best loan path for this borrower, and why?
This skill does NOT re-run qualification logic. It consumes completed QualResult objects and applies multi-objective scoring, goal alignment, sensitivity analysis, and Always-Approved state detection.
Inputs required:
BorrowerGoal — the borrower's stated primary objectiveConstraintList — from Constraint Detection SkillOutputs produced:
OptimizationResult — scored programs, composite rankings, goal alignmentSensitivityAnalysis — how results shift with ±0.25% rate, ±20 credit scoreAlwaysApprovedState — the nearest feasible fully-qualified outcomeOptimizationLineageTrace — every scoring decision with rationale
Every optimization is goal-anchored. The borrower's stated goal determines
which scoring dimensions receive elevated weight.
GOAL_LOWEST_PAYMENT:
Priority: monthly_payment_score
Trade: accept higher CTC, higher total MI cost
Weight boost: payment weight → 0.50 (from 0.35)
Weight cut: CTC weight → 0.10 (from 0.20)
GOAL_LOWEST_CTC:
Priority: cash_to_close_score
Trade: accept higher payment, higher total MI
Weight boost: CTC weight → 0.40 (from 0.20)
Weight cut: payment weight → 0.20 (from 0.35)
GOAL_MINIMIZE_MI:
Priority: total_mi_cost_score
Trade: accept higher payment or CTC to eliminate/reduce MI
Weight boost: MI weight → 0.40 (from 0.20)
Weight cut: payment weight → 0.20 (from 0.35)
GOAL_MAXIMIZE_APPROVAL_ODDS:
Priority: approval_certainty_score
Trade: accept any cost for highest-certainty path
Weight boost: certainty weight → 0.45 (from 0.20)
Weight cut: MI weight → 0.05 (from 0.20)
GOAL_BEST_RATE:
Priority: rate_score (added dimension, weight 0.30)
Trade: accept higher CTC for lower rate
Note: rate_score is only active for GOAL_BEST_RATE
GOAL_BALANCED (default if none stated):
Use standard weights: pay=0.35, mi=0.20, ctc=0.20, cert=0.20, qual=0.05
Stage 1 — Validate inputs
Stage 2 — Extract and normalize program results
Stage 3 — Score ineligible programs (partial — for gap awareness)
Stage 4 — Score eligible programs on all dimensions
Stage 5 — Apply goal-based weight adjustment
Stage 6 — Compute composite scores
Stage 7 — Apply sensitivity analysis
Stage 8 — Detect Always-Approved state
Stage 9 — Generate optimization narrative
Stage 10 — Emit OptimizationResult
From each QualResult, extract:
payment_monthly:
VA: pitia (no MI in payment — funding fee is financed one-time)
CONV: pitia (includes monthly PMI if applicable)
FHA: pitim (P&I + T + I + HOA + MIP — MIP is in payment)
DSCR: pitia (no MI)
total_mi_lifetime:
VA: funding_fee_financed_amount (one-time equivalent; not recurring monthly)
CONV: lifetime_pmi (monthly PMI × cancel_month)
FHA: lifetime_mip (monthly MIP × mip_duration_months)
DSCR: 0
mi_cancels:
VA: true (funding fee is one-time — no ongoing MI)
CONV: true (PMI cancels at 78% LTV per HPA)
FHA: true IF fha_ltv_base ≤ 0.90 (11-year duration), false IF > 0.90 (life of loan)
DSCR: N/A (no MI)
cash_to_close:
All: total_cash_to_close from respective QualResult
approval_certainty:
QUALIFIED / DSCR_ELIGIBLE_STRONG / DSCR_ELIGIBLE_PASS: 0.90
QUALIFIED_TOTAL_ACCEPT / QUALIFIED_DU_APPROVE: 0.85
QUALIFIED_MANUAL_UW / DSCR_CONDITIONAL: 0.70
CONDITIONAL (income or property): 0.65
INELIGIBLE_*: 0.00
rate_for_comparison:
Use the qualifying rate from each program's QualResult.
Note: DSCR rates are non-QM — not directly comparable to GSE rates.
Ineligible programs are still scored on the dimensions they would have achieved, with approval_certainty = 0. This creates the "gap map" — showing how close an ineligible program is to qualifying.
FOR each INELIGIBLE program:
Score all dimensions EXCEPT approval_certainty (which = 0)
Compute partial_composite using standard weights
Identify: which dimension caused the 0 (the binding constraint)
gap_score = partial_composite × approval_certainty_score [= 0]
proximity_score = partial_composite [what it would have been if approved]
Note: High proximity_score → program would be excellent IF constraints resolved
Low proximity_score → program was not a good fit even if eligible
All scores are 0–100. Higher is always better for the borrower.
pay_floor = 2,000 (best any program could realistically produce for this property)
pay_ceil = 5,000 (affordability wall — above this, most borrowers are stressed)
OVERRIDE: If borrower's PITIA exceeds 43% of gross monthly income at pay_floor,
adjust pay_floor = gmi × 0.28 (minimum viable front-end ratio)
adjust pay_ceil = gmi × 0.50 (absolute maximum)
payment_score = 100 × (1 - (payment_monthly - pay_floor) / (pay_ceil - pay_floor))
payment_score = CLAMP(payment_score, 0, 100)
MI is penalized more heavily when it cannot be cancelled.
effective_mi:
IF mi_cancels = true: effective_mi = total_mi_lifetime
IF mi_cancels = false: effective_mi = total_mi_lifetime × 1.30 (30% life-of-loan penalty)
IF total_mi_lifetime = 0: effective_mi = 0
mi_score = max(0, 100 - (effective_mi / 700))
NOTE: $700 of effective MI cost reduces score by 1 point.
$70,000 lifetime MI → score ≈ 0
$0 MI → score = 100
EXCEPTION: VA funding fee is treated as cancelable (one-time, no ongoing obligation).
VA gets mi_cancels = true for scoring purposes.
Property value used as denominator for normalization.
property_value = from BorrowerProfile
ctc_pct = cash_to_close / property_value
ctc_score = 100 × (1 - ctc_pct / 0.25)
ctc_score = CLAMP(ctc_score, 0, 100)
NOTE: 0% down → ctc_pct ≈ 0.02–0.04 (closing costs only) → score ≈ 84–92
3.5% down → ctc_pct ≈ 0.05–0.08 → score ≈ 68–80
20% down → ctc_pct ≈ 0.22 → score ≈ 12
25% down → ctc_pct = 0.25 → score = 0
certainty_score = approval_certainty × 100
Values per Stage 2 normalization (see above).
INELIGIBLE programs: certainty_score = 0 (for composite)
Fixed bonus applied to composite — not a weighted dimension.
VA: +15 (veteran benefit, no recurring MI, full utilization of earned benefit)
CONVENTIONAL: +10 (mainstream product, PMI cancels, best lender selection)
FHA: +0 (baseline — accessible but MI-heavy)
DSCR: +5 (correct tool for investment; specialized)
NOTE: Quality bonus rewards using the optimal program for the borrower's situation.
VA borrowers who take VA loans are maximizing their benefit.
Conventional borrowers with strong credit and equity maximize PMI cancelability.
IF borrower_goal = GOAL_BEST_RATE:
rate_floor = 5.00% (best case — market floor)
rate_ceil = 9.00% (high rate environment ceiling)
rate_score = 100 × (1 - (program_rate - rate_floor) / (rate_ceil - rate_floor))
rate_score = CLAMP(rate_score, 0, 100)
Add rate_score × 0.30 to composite
Reduce payment weight by 0.30 (overlapping signal)
STANDARD WEIGHTS (GOAL_BALANCED):
payment_score: 0.35
mi_score: 0.20
ctc_score: 0.20
certainty_score: 0.20
quality_bonus: 0.05
GOAL_LOWEST_PAYMENT:
payment_score: 0.50
mi_score: 0.15
ctc_score: 0.10
certainty_score: 0.20
quality_bonus: 0.05
GOAL_LOWEST_CTC:
payment_score: 0.20
mi_score: 0.15
ctc_score: 0.40
certainty_score: 0.20
quality_bonus: 0.05
GOAL_MINIMIZE_MI:
payment_score: 0.20
mi_score: 0.40
ctc_score: 0.15
certainty_score: 0.20
quality_bonus: 0.05
GOAL_MAXIMIZE_APPROVAL_ODDS:
payment_score: 0.20
mi_score: 0.05
ctc_score: 0.10
certainty_score: 0.60
quality_bonus: 0.05
NOTE: All weights must sum to 1.00 (excluding quality_bonus, which is additive).
Verify: payment + mi + ctc + certainty = 1.00 before applying.
composite_score = (payment_score × w_pay)
+ (mi_score × w_mi)
+ (ctc_score × w_ctc)
+ (certainty_score × w_cert)
+ quality_bonus [additive, not weighted]
[+ rate_score × 0.30 IF GOAL_BEST_RATE]
composite_score = ROUND(composite_score, 2)
INTERPRETATION:
90–115+: Excellent fit — strong recommendation
70–89: Good fit — viable with minor considerations
50–69: Adequate — conditions or tradeoffs present
30–49: Marginal — significant constraints or suboptimal fit
0–29: Poor fit — should only appear if no better options exist
0 (INELIGIBLE): Program blocked — shown in gap analysis only
For each eligible program, compute how composite score changes under:
SENSITIVITY A — Rate ±0.25%:
Re-compute payment_monthly at rate ± 0.25%
Re-score payment_score and ctc_score (prepaid interest changes slightly)
Recompute composite
delta_rate_up = composite(rate + 0.25%) - composite(rate)
delta_rate_down = composite(rate - 0.25%) - composite(rate)
SENSITIVITY B — Credit score ±20 points:
For Conventional: check if LLPA tier changes → rate change → re-score
For FHA: check if MIP rate or AUS path changes
For VA: no credit-based pricing — no change
delta_score_up = impact of score + 20
delta_score_down = impact of score - 20
SENSITIVITY C — Down payment ±5%:
Re-compute LTV, re-check eligibility gates, re-score CTC
Note if LTV change affects: PMI threshold, LLPA tier, MIP duration
OUTPUT per program:
sensitivity_rating: STABLE | SENSITIVE | HIGHLY_SENSITIVE
STABLE: composite change < 5 points across all sensitivities
SENSITIVE: composite change 5–15 points on any sensitivity
HIGHLY_SENSITIVE: composite change > 15 points on any sensitivity
SIMPLIFIED GEAR 1 APPROACH:
Compute rate sensitivity only (B and C are flags, not full recomputes).
Rate sensitivity: re-score payment at ±0.25% using PMT formula.
Flag CREDIT_SENSITIVE if borrower is within 20 pts of a tier boundary.
Flag LTV_SENSITIVE if borrower is within 3% LTV of a threshold.
The Always-Approved state is a foundational Clarity Engine concept:
"There is ALWAYS an approved outcome — the question is what it requires."
ALWAYS_APPROVED_STATE detection:
Step 1: Count ELIGIBLE programs.
IF ≥ 1 ELIGIBLE program exists:
always_approved_state = CURRENTLY_ACHIEVABLE
nearest_approved = highest-scoring eligible program
action_required = none [borrower can proceed now]
Step 2: IF 0 ELIGIBLE programs:
always_approved_state = ACHIEVABLE_WITH_ACTION
Identify the INELIGIBLE program with the highest proximity_score.
That program = the nearest achievable path.
For each binding constraint:
Compute the minimum change required to resolve it:
DTI constraint: income_increase_needed OR payment_reduction_needed
Credit constraint: score_gap = minimum_required - qualifying_score
LTV constraint: additional_down_needed = (ltv - max_ltv) × property_value
CTC constraint: additional_funds_needed = ctc_gap
always_approved_resolution:
Type: CREDIT | DTI | DOWN_PAYMENT | INCOME | MULTIPLE
Minimum action: [specific number — no vague language]
Timeline estimate:
CREDIT: 30–90 days (score improvement)
DTI: immediate (co-borrower) OR ongoing (pay down debt)
DOWN_PAYMENT: depends on savings rate
INCOME: 2 years (history requirement)
Step 3: Present Always-Approved state clearly:
"Even if [program X] is not available today, [program Y] is achievable
[now / with $X additional down / in ~N months by improving score N points]."
ALWAYS_APPROVED_STATE values:
CURRENTLY_ACHIEVABLE — at least one program qualifies now
ACHIEVABLE_WITH_CREDIT — score improvement resolves binding constraint
ACHIEVABLE_WITH_DOWN — additional down payment resolves LTV/CTC
ACHIEVABLE_WITH_INCOME — co-borrower or income documentation resolves DTI
ACHIEVABLE_WITH_TIME — seasoning period required (bankruptcy, foreclosure)
ACHIEVABLE_MULTIPLE_ACTIONS — 2+ constraints, each with resolution path
Generate a structured narrative — not a generic summary.
NARRATIVE COMPONENTS (always include):
1. Primary recommendation: [PROGRAM] — one sentence, specific
2. Why this program wins: name the top 2 dimensions that drove the score
3. Key tradeoff: what does this recommendation cost vs the next option?
4. Always-Approved state: one sentence on current status
5. Single most important next action (if any)
NARRATIVE RULES:
Never hedge on the primary recommendation. One program wins.
Use specific numbers. "VA saves $436/month vs FHA" not "VA has lower payments."
Frame tradeoffs, not downsides. "FHA requires $8,679 more cash-to-close" not "FHA is worse."
Always include the Always-Approved state — even if trivially positive.
Maximum length: 5 sentences. If more needed → use Explanation Skill.
{
"schema_version": "clarity_engine_v1.0",
"skill": "OPTIMIZATION",
"skill_version": "1.0",
"deal_id": "string",
"borrower_id": "string",
"created_at": "ISO 8601 UTC",
"borrower_goal": "GOAL_BALANCED | GOAL_LOWEST_PAYMENT | GOAL_LOWEST_CTC | GOAL_MINIMIZE_MI | GOAL_MAXIMIZE_APPROVAL_ODDS | GOAL_BEST_RATE",
"weights_applied": {
"payment": 0.0,
"mi": 0.0,
"ctc": 0.0,
"certainty": 0.0,
"quality_bonus": "additive"
},
"program_scores": [
{
"program": "VA | CONVENTIONAL | FHA | DSCR",
"status": "QUALIFIED | INELIGIBLE | CONDITIONAL",
"payment_score": 0.0,
"mi_score": 0.0,
"ctc_score": 0.0,
"certainty_score": 0.0,
"quality_bonus": 0,
"composite_score": 0.0,
"rank": 1,
"sensitivity_rating": "STABLE | SENSITIVE | HIGHLY_SENSITIVE"
}
],
"primary_recommendation": {
"program": "string",
"composite_score": 0.0,
"rationale": "string",
"key_tradeoff_vs_next": "string"
},
"always_approved_state": {
"state": "CURRENTLY_ACHIEVABLE | ACHIEVABLE_WITH_ACTION",
"nearest_approved_program": "string",
"action_required": "string | null",
"action_type": "NONE | CREDIT | DTI | DOWN_PAYMENT | INCOME | TIME | MULTIPLE",
"minimum_action_amount": null,
"timeline_estimate": "string | null"
},
"sensitivity_summary": {
"rate_up_0_25pct": "string",
"rate_down_0_25pct": "string",
"credit_sensitive": false,
"ltv_sensitive": false
},
"optimization_narrative": "string",
"flags": [],
"lineage_trace": {}
}
Inputs from upstream skills (Router canonical values):
BorrowerGoal: GOAL_BALANCED (not specified — default)
VA QualResult (from Router):
status: QUALIFIED
pitia: 3,363.83 (loan 434,137.50 incl. funding fee, rate 6.50%)
total_mi_lifetime: 9,137.50 (funding fee financed — one-time, not recurring)
mi_cancels: true (one-time fee — no ongoing MI obligation)
cash_to_close: 12,750.00
approval_certainty: 0.90
rate: 6.50%
FHA QualResult (from FHA Skill):
status: QUALIFIED_TOTAL_ACCEPT
pitim: 3,456.85
total_mi_lifetime: 67,669.20 (life of loan — does not cancel; LTV > 90%)
mi_cancels: false
cash_to_close: 26,085.96
approval_certainty: 0.85
rate: 6.50%
CONV QualResult (from Conventional Skill):
status: INELIGIBLE_DTI
pitia: 3,857.30 (computed — not achievable)
total_mi_lifetime: 53,935.78 (cancelable at 80% LTV)
mi_cancels: true
cash_to_close: 24,159.38
approval_certainty: 0.00
rate: 7.50%
Stage 3 — Ineligible Program Gap Scoring (CONV)
property_value = 425,000; pay_floor=2,000; pay_ceil=5,000
pay_score(3857.30):
100 × (1 - (3857.30 - 2000) / 3000) = 100 × (1 - 1857.30/3000) = 38.09
mi_score(53935.78, cancels=True):
max(0, 100 - 53935.78/700) = max(0, 100 - 77.05) = 22.95
ctc_score(24159.38):
24159.38/425000 = 0.05685; 100 × (1 - 0.05685/0.25) = 77.26
cert_score(0.0) = 0.00
CONV proximity_score (what it would score if approved):
38.09×0.35 + 22.95×0.20 + 77.26×0.20 + 100.00×0.20 + 10
= 13.33 + 4.59 + 15.45 + 20.00 + 10.00 = 63.37
CONV composite (ineligible — cert = 0):
38.09×0.35 + 22.95×0.20 + 77.26×0.20 + 0.00×0.20 + 10
= 13.33 + 4.59 + 15.45 + 0.00 + 10.00 = 43.37
Stage 4 — Eligible Program Scoring
property_value = 425,000; pay_floor=2,000; pay_ceil=5,000
VA:
pay_score(3363.83):
100 × (1 - (3363.83 - 2000) / 3000) = 100 × (1 - 1363.83/3000) = 54.54
mi_score(9137.50, cancels=True):
max(0, 100 - 9137.50/700) = max(0, 100 - 13.05) = 86.95
ctc_score(12750.00):
12750.00/425000 = 0.03000; 100 × (1 - 0.03000/0.25) = 88.00
cert_score(0.90): 90.00
quality_bonus: +15
composite_VA = 54.54×0.35 + 86.95×0.20 + 88.00×0.20 + 90.00×0.20 + 15
= 19.09 + 17.39 + 17.60 + 18.00 + 15.00
= 87.08
FHA:
pay_score(3456.85):
100 × (1 - (3456.85 - 2000) / 3000) = 100 × (1 - 1456.85/3000) = 51.44
mi_score(67669.20, cancels=False):
effective = 67669.20 × 1.30 = 87,969.96
max(0, 100 - 87969.96/700) = max(0, 100 - 125.67) = 0.00
ctc_score(26085.96):
26085.96/425000 = 0.06138; 100 × (1 - 0.06138/0.25) = 75.45
cert_score(0.85): 85.00
quality_bonus: +0
composite_FHA = 51.44×0.35 + 0.00×0.20 + 75.45×0.20 + 85.00×0.20 + 0
= 18.00 + 0.00 + 15.09 + 17.00 + 0.00
= 50.09
Composite Score Summary:
VA: 87.08 (rank 1) — RECOMMENDED
FHA: 50.09 (rank 2)
CONV: 43.37 (rank 3 — ineligible, gap display only)
Stage 7 — Rate Sensitivity (Gear 1)
VA loan: 434,137.50; base rate: 6.50%; T+I component: 619.79
VA at rate + 0.25% (6.75%):
pmt_factor(6.75%) = 0.0064860
New P&I = 434,137.50 × 0.0064860 = 2,815.80 (vs current 2,744.04)
PITIA: 3,435.59 (delta +71.76/month)
pay_score(3435.59): 52.15 (vs 54.54)
composite delta: −0.84 pts → STABLE
VA at rate − 0.25% (6.25%):
pmt_factor(6.25%) = 0.0061531
New P&I = 434,137.50 × 0.0061531 = 2,673.05
PITIA: 3,292.84 (delta −70.99/month)
pay_score(3292.84): 56.90 (vs 54.54)
composite delta: +0.83 pts → STABLE
sensitivity_rating: STABLE (all composite deltas < 5 pts)
Stage 8 — Always-Approved State
ELIGIBLE programs: VA (QUALIFIED), FHA (QUALIFIED_TOTAL_ACCEPT)
always_approved_state = CURRENTLY_ACHIEVABLE
nearest_approved = VA
action_required = null
Stage 9 — Optimization Narrative
VA is the clear recommendation — lower payment ($3,363.83 vs $3,456.85), dramatically
less MI ($9,137 one-time vs $67,669 life-of-loan), and $13,336 less cash-to-close.
FHA is a fully approved backup — DTI 50.15% clears TOTAL Scorecard — but carries
$58,531 more in lifetime mortgage insurance that will never cancel.
The borrower is currently approved. VA closes now.
Stage 10 — Final OptimizationResult:
primary_recommendation: VA
composite_score: 87.08
rationale: "VA: pay=54.54, MI=86.95, CTC=88.00, cert=90.00, quality+15."
key_tradeoff_vs_next: "FHA: $93/mo lower payment gap but $58,531 more lifetime MI and $13,336 more CTC."
always_approved_state: CURRENTLY_ACHIEVABLE
nearest: VA | action_required: null
sensitivity_summary:
rate_up_0_25pct: "composite −0.84 pts (STABLE)"
rate_down_0_25pct: "composite +0.83 pts (STABLE)"
credit_sensitive: false
ltv_sensitive: false
FO-01: Averaging program qualification results
Never average DTI, LTV, or DSCR across programs.
Each program has its own rules — composite scoring compares outcomes, not inputs.
FO-02: Recommending an INELIGIBLE program as primary
An ineligible program may appear in gap analysis — never as the recommendation.
Always-Approved state identifies the path to eligible — it is not itself a recommendation.
FO-03: Omitting the Always-Approved state
Every OptimizationResult must include an Always-Approved assessment.
Even if trivially positive ("borrower is approved now"), it must be stated.
FO-04: Vague recommendation language
"VA may be better" → FORBIDDEN
"VA saves $435.97/month vs FHA" → REQUIRED
All recommendations must reference specific dollar amounts and composite scores.
FO-05: Applying goal weights without documenting them
If goal weights differ from GOAL_BALANCED defaults, the weights_applied field
in the output must reflect the actual weights used.
FO-06: Using relative normalization with < 3 programs
Relative normalization (0 = worst, 100 = best in set) produces degenerate scores
when only 1–2 programs are eligible. Always use absolute benchmarks.
FO-07: Ignoring the quality bonus in composite
The quality bonus is additive — it must be added AFTER the weighted sum.
It is not included in the weighted dimensions.
| Skill | Relationship |
|---|---|
Clarity_Engine_VA_Module_SKILL.md | Input — provides VAQualResult |
Clarity_Engine_Conventional_SKILL.md | Input — provides ConvQualResult |
Clarity_Engine_FHA_SKILL.md | Input — provides FHAQualResult |
Clarity_Engine_DSCR_SKILL.md | Input — provides DSCRQualResult |
Clarity_Engine_Constraint_Detection_SKILL.md | Input — provides ConstraintList |
Clarity_Engine_Scenario_Generation_SKILL.md | Downstream — receives OptimizationResult |
Clarity_Engine_Ranking_SKILL.md | Downstream — receives OptimizationResult |
Clarity_Engine_Explanation_SKILL.md | Downstream — narrative expansion |
Clarity Engine — Optimization Skill v1.0 | CONFIDENTIAL — PreFi, Inc. / Purpose Technology, Inc. d/b/a Purlend