Version: 1.0 | Status: Implementation-Ready — Gear 1
Scope: Produces the definitive ranked recommendation list across all qualified mortgage programs. Takes OptimizationResult and ScenarioSet as inputs and emits a RankedProgramList — the final, structured, confidence-weighted program ordering with rationale ready for the Explanation Skill or direct borrower delivery.
Confidential: PreFi, Inc. / Purpose Technology, Inc. d/b/a Purlend
The Ranking Skill is the final arbitration layer before explanation and delivery. While the Optimization Skill scores programs, the Ranking Skill resolves ties, applies tiebreaker rules, assigns confidence scores, produces the 1–4 program ordered list, and generates the single final recommendation with a clear, defensible rationale.
Inputs required:
OptimizationResult (from Optimization Skill)ScenarioSet (from Scenario Generation Skill — may be empty if no constraints)QualResult objects (VA, Conv, FHA, DSCR)Outputs produced:
RankedProgramList — 1–4 programs in priority orderFinalRecommendation — single best-fit program with rationaleConfidenceScores — 0.0–1.0 per programRankingLineageTrace
Stage 1 — Validate inputs
Stage 2 — Collect eligible programs with composite scores
Stage 3 — Apply tiebreaker rules (if any programs within 5 points)
Stage 4 — Assign confidence scores
Stage 5 — Apply scenario integration (does any scenario change the rank?)
Stage 6 — Finalize ranked list
Stage 7 — Generate FinalRecommendation
Stage 8 — Emit RankedProgramList
From OptimizationResult.program_scores:
Filter: status NOT in [INELIGIBLE_*, DSCR_FAIL]
Sort by composite_score descending
IF zero eligible programs:
ranking_status = NO_ELIGIBLE_PROGRAMS
primary_recommendation = null
always_approved_action = [from OptimizationResult.always_approved_state]
STOP — emit empty ranked list with action required.
IF one eligible program:
ranking_status = SINGLE_PROGRAM
primary_recommendation = that program
confidence = approval_certainty from QualResult
No tiebreaker needed.
IF two or more eligible programs:
ranking_status = MULTI_PROGRAM
Apply tiebreaker rules (Stage 3) if top two within 5 composite points.
Applied in priority order when two programs are within 5 composite points.
TIEBREAKER 1 — MI Cancelability:
Program with cancellable MI (or no MI) outranks program with life-of-loan MI.
Rationale: Uncancellable MI is a permanent drag — equivalent to a permanent rate premium.
TIEBREAKER 2 — Approval Certainty:
Higher approval_certainty wins.
Rationale: A slightly lower-scoring program that is certain beats a higher-scoring program
that is conditional on AUS, manual underwrite, or overlays.
TIEBREAKER 3 — Cash-to-Close:
Lower cash_to_close wins.
Rationale: Immediate capital requirement is a real constraint; monthly payment optimizes
over 30 years but CTC must be available at closing.
TIEBREAKER 4 — Monthly Payment:
Lower monthly payment wins.
Rationale: Long-run sustainability — affordability shock if income changes.
TIEBREAKER 5 — Program Mainstream Status:
Conventional > FHA > VA > DSCR (for general tiebreak — NOT for veteran borrowers)
EXCEPTION: For eligible veterans, VA > Conventional > FHA (veteran benefit maximization)
Rationale: Mainstream programs offer broader lender selection and secondary market access.
NOTE: Tiebreaker 5 is the last resort only. Programs are almost never tied after TB 1–4.
Confidence is distinct from composite score.
Composite measures outcome quality (how good is this loan?).
Confidence measures outcome certainty (how likely is this to close?).
CONFIDENCE COMPONENTS:
BASE_CONFIDENCE from QualResult approval_certainty:
QUALIFIED / DSCR_ELIGIBLE_*: 0.90
QUALIFIED_TOTAL_ACCEPT (DU/TOTAL): 0.85
QUALIFIED_MANUAL_UW: 0.70
CONDITIONAL: 0.65
CONFIDENCE ADJUSTMENTS (additive):
CTC_MET (surplus > 5%): +0.03
RESERVES_STRONG (surplus > 3mo): +0.03
DTI_COMFORTABLE (< limit by 5+ pts): +0.02
HIGH_RESIDUAL (VA > 120% threshold): +0.02
CREDIT_STRONG (score ≥ 740): +0.02
LAYERED_RISK (3+ risk flags): −0.10
DTI_TIGHT (within 1% of limit): −0.05
CTC_TIGHT (surplus < 2%): −0.05
DSCR_CONDITIONAL (ratio < 1.00): −0.10
MANUAL_UW_REQUIRED: −0.05
confidence = CLAMP(base + adjustments, 0.40, 0.99)
confidence = ROUND(confidence, 2)
CONFIDENCE INTERPRETATION:
0.90–0.99: Very high — expect smooth approval, no surprises
0.80–0.89: High — standard process, minor conditions expected
0.70–0.79: Moderate — conditions or manual review likely
0.60–0.69: Lower — conditional approval, possible re-submission risk
0.40–0.59: Low — significant uncertainty, advisor review required
Check if any ScenarioSet scenario changes the ranking:
FOR each scenario in ScenarioSet:
IF scenario.programs_affected includes a currently INELIGIBLE program:
IF scenario.timeline_estimate ≤ 90 days:
flag NEAR_TERM_PROGRAM_UNLOCK — note in RankedProgramList
IF scenario.effort_impact_score ≥ 70:
note: "Program [X] available in [timeline] with [action]"
IF scenario.type = PROGRAM_SWITCH and scenario.rank = 1:
This scenario IS the primary recommendation — confirm alignment with rank order.
NOTE: Scenarios do not change the current ranked list — they extend it with future-state options.
The ranked list reflects today's approved programs only.
Future-state options appear as narrative additions, not ranking changes.
RANKED_PROGRAM_LIST rules:
1. Only eligible programs appear in the ranked list (INELIGIBLE = excluded)
2. Ranked 1 = primary recommendation
3. Ranked 2 = backup (if exists)
4. Maximum 4 programs in list (even if more are eligible — prune duplicative)
5. If DSCR eligible AND standard program (VA/Conv/FHA) also eligible:
DSCR is always ranked LAST (investment product — different use case)
DISPLAY RULES:
Each program in ranked list includes:
rank, program_name, composite_score, confidence, monthly_payment,
total_mi_lifetime, cash_to_close, key_advantage, key_limitation
Ineligible programs are NOT shown in ranked list — they appear only in
scenario section as future-state options.
FinalRecommendation = Ranked #1 program
RECOMMENDATION STATEMENT FORMAT:
"[PROGRAM] — [composite score]/100, [confidence×100]% confidence"
"Primary driver: [top-scoring dimension name and value]"
"Key advantage over [rank #2]: [specific dollar amount or percentage]"
"One risk to monitor: [single most important flag or condition]"
RECOMMENDATION RULES:
Never hedge. One program wins. State it clearly.
Always name the specific advantage over the next-best option.
Always name one risk — even if confidence is 0.99 — honesty builds trust.
If confidence < 0.70: add "Recommend advisor review before proceeding."
{
"schema_version": "clarity_engine_v1.0",
"skill": "RANKING",
"skill_version": "1.0",
"deal_id": "string",
"borrower_id": "string",
"created_at": "ISO 8601 UTC",
"ranking_status": "MULTI_PROGRAM | SINGLE_PROGRAM | NO_ELIGIBLE_PROGRAMS",
"tiebreaker_applied": false,
"tiebreaker_rule_used": null,
"ranked_programs": [
{
"rank": 1,
"program": "string",
"composite_score": 0.0,
"confidence": 0.00,
"monthly_payment": 0.00,
"total_mi_lifetime": 0.00,
"mi_cancels": false,
"cash_to_close": 0.00,
"key_advantage": "string",
"key_limitation": "string",
"qualification_status": "string"
}
],
"final_recommendation": {
"program": "string",
"composite_score": 0.0,
"confidence": 0.00,
"statement": "string",
"primary_driver": "string",
"advantage_over_next": "string",
"risk_to_monitor": "string"
},
"near_term_unlocks": [],
"flags": [],
"lineage_trace": {}
}
Inputs:
OptimizationResult:
VA: composite=87.08, cert=0.90, status=QUALIFIED
FHA: composite=50.09, cert=0.85, status=QUALIFIED_TOTAL_ACCEPT
CONV: composite=43.37, cert=0.00, status=INELIGIBLE_DTI
ScenarioSet: S1=PROGRAM_SWITCH(VA,95), S2=DEBT_PAYOFF(CONV,44), S3=CO_BORROWER(CONV,58)
Stage 2 — Eligible Programs:
VA: composite=87.08
FHA: composite=50.09
CONV: INELIGIBLE — excluded
Stage 3 — Tiebreaker:
VA 87.08 vs FHA 50.09 — difference = 37.0 pts (> 5 threshold)
No tiebreaker needed. VA wins clearly.
Stage 4 — Confidence Scores:
VA:
base = 0.90 (QUALIFIED)
CTC_MET: surplus = $15,355.36 / $12,750 = 120.4% → +0.03
RESERVES_STRONG: $50,000 available vs $16,143 required → +0.03
DTI_COMFORTABLE: back_dti = 47.37% vs 41% limit?
Actually VA uses residual income not DTI limit — back_dti ≈ 47% for VA is standard
Residual income met with surplus — +0.02
CREDIT_STRONG: score not specified as ≥740 — 0
confidence_VA = CLAMP(0.90 + 0.03 + 0.03 + 0.02, 0.40, 0.99) = 0.98
FHA:
base = 0.85 (QUALIFIED_TOTAL_ACCEPT)
CTC_MET: surplus = $95,000 - $26,086 (approx) — assuming funds available
DTI_TIGHT: back_dti = 50.15%, limit ≈ 57% — not tight → 0
confidence_FHA = CLAMP(0.85 + 0.03 + 0.03, 0.40, 0.99) = 0.91
Stage 5 — Scenario Integration:
S2 (DEBT_PAYOFF): CONV unlock, timeline = depends on savings → NEAR_TERM_UNLOCK flag if < 90 days
payoff ~$906/month obligations — depends on available funds
flag: CONVENTIONAL_AVAILABLE_WITH_DEBT_PAYOFF
S3 (CO_BORROWER): CONV unlock, timeline = immediate if co-borrower available
flag: CONVENTIONAL_AVAILABLE_WITH_CO_BORROWER
Stage 6 — Ranked List:
Rank 1: VA — composite 87.08, confidence 0.98
Rank 2: FHA — composite 50.09, confidence 0.91
(CONV excluded — INELIGIBLE)
Stage 7 — Final Recommendation:
program: VA
composite_score: 87.08
confidence: 0.98
statement: "VA Loan — 87.08/100 composite, 98% confidence."
primary_driver: "MI dimension: VA one-time $9,137 vs FHA $67,669 life-of-loan (score 86.95 vs 0.00)."
advantage_over_next: "Saves $58,531 in lifetime mortgage insurance and $13,336 in cash-to-close vs FHA."
risk_to_monitor: "VA eligibility must be confirmed via COE — verify entitlement before committing."
FR-01: Including INELIGIBLE programs in the ranked list
The ranked list is current eligible programs only.
INELIGIBLE programs appear only in the scenario section (future-state).
FR-02: Applying tiebreaker rules when gap > 5 points
Tiebreakers are only for programs within 5 composite points.
If gap > 5, the higher-scoring program wins — no tiebreaker logic needed.
FR-03: Assigning confidence > 0.99 or < 0.40
Confidence is always clamped to [0.40, 0.99].
No loan is 100% certain — 0.99 is the maximum.
No eligible loan should score below 0.40 — if it does, it should be CONDITIONAL.
FR-04: Omitting the risk_to_monitor field
Every recommendation must include one specific risk.
"No risks identified" is not a valid entry.
The honest identification of one risk builds borrower trust.
FR-05: Ranking DSCR above a standard program for a primary residence scenario
DSCR is an investment product. It is always ranked last if other programs are eligible.
This rule overrides composite score for DSCR vs standard programs.
| Skill | Relationship |
|---|---|
Clarity_Engine_Optimization_SKILL.md | Required input — composite scores |
Clarity_Engine_Scenario_Generation_SKILL.md | Required input — scenarios for integration |
Clarity_Engine_Overlay_SKILL.md | Downstream — overlays adjust confidence |
Clarity_Engine_Explanation_SKILL.md | Downstream — narrative from FinalRecommendation |
Clarity_Engine_Audit_Trace_SKILL.md | Downstream — lineage trace |
Clarity Engine — Ranking Skill v1.0 | CONFIDENTIAL — PreFi, Inc. / Purpose Technology, Inc. d/b/a Purlend