Version: 1.0 | Status: Implementation-Ready — Gear 1
Scope: Generates 3–5 concrete, actionable alternative scenarios when the borrower's primary qualification path has constraints, gaps, or suboptimal outcomes. Each scenario is fully specified: what changes, what it costs, how long it takes, and how much closer it gets to the borrower's goal.
Confidential: PreFi, Inc. / Purpose Technology, Inc. d/b/a Purlend
The Scenario Generation Skill answers: "If not this, then what — and exactly how do I get there?"
When a borrower is INELIGIBLE, CONDITIONAL, or qualifies but not optimally, this skill produces a structured set of alternative paths. Each scenario is a precise, executable plan — not a vague suggestion.
Trigger conditions (invoke this skill when):
qualification_status = INELIGIBLE_*qualification_status = CONDITIONALalways_approved_state ≠ CURRENTLY_ACHIEVABLEInputs required:
OptimizationResult (from Optimization Skill)ConstraintList (from Constraint Detection Skill)BorrowerProfile (from Borrower Profile Skill)Outputs produced:
ScenarioSet — 3–5 ranked scenarios, each fully specifiedScenarioLineageTrace — constraint resolution logic for each scenario
Eight scenario types. Select the 3–5 most relevant based on binding constraints.
TYPE 1: CREDIT_IMPROVEMENT
Trigger: qualifying_credit_score below any program threshold
Resolution: identify the minimum score improvement needed, estimate timeline
Key metrics: score_gap, timeline_months, specific_actions
TYPE 2: DOWN_PAYMENT_INCREASE
Trigger: LTV exceeds max for eligible programs; or borrower in suboptimal tier
Resolution: compute additional down payment needed for LTV threshold
Key metrics: additional_funds_needed, LTV after, impact on rate/MI/tier
TYPE 3: DEBT_PAYOFF
Trigger: DTI exceeds limit; back-end DTI is the binding constraint
Resolution: identify which obligations to pay off to bring DTI into compliance
Key metrics: payoff_amount, monthly_savings, new_DTI
TYPE 4: CO_BORROWER_ADD
Trigger: DTI constraint; insufficient income; AUS downgrade risk
Resolution: model a co-borrower with adequate income to resolve DTI
Key metrics: co_borrower_income_needed, combined_DTI, combined_residual
TYPE 5: RATE_BUYDOWN
Trigger: borrower goal is GOAL_LOWEST_PAYMENT or GOAL_BEST_RATE
Resolution: compute cost of buying down rate by 0.25% / 0.50% / 1.00%
Key metrics: buydown_cost (points), monthly_savings, break-even months
TYPE 6: LOAN_AMOUNT_REDUCTION
Trigger: DTI constraint that cannot be resolved via income; or LTV constraint
Resolution: reduce purchase price / loan amount to bring into compliance
Key metrics: max_loan_at_compliance, implied_max_purchase_price
TYPE 7: PROGRAM_SWITCH
Trigger: best program is ineligible; viable alternative exists
Resolution: model borrower on next-best eligible program
Key metrics: program_delta (payment, MI, CTC differences), tradeoffs
TYPE 8: WAIT_AND_SEASON
Trigger: bankruptcy, foreclosure, or short sale waiting period constraint
Resolution: identify exactly when waiting period expires
Key metrics: event_date, waiting_period_months, eligible_date, program_specific
Stage 1 — Validate inputs
Stage 2 — Identify binding constraints from ConstraintList
Stage 3 — Map constraints to scenario types
Stage 4 — Generate each scenario (see Stage 4 logic below)
Stage 5 — Score each scenario by effort-to-impact ratio
Stage 6 — Rank and filter to top 3–5
Stage 7 — Emit ScenarioSet
From ConstraintList, extract all constraints with severity = BLOCKING or ADVISORY.
BINDING_CONSTRAINTS:
BLOCKING: directly prevents qualification (HARD_STOP)
ADVISORY: qualification possible but suboptimal
For each binding constraint, record:
constraint_type
affected_programs (which programs it blocks or degrades)
resolution_type (what category of action resolves it)
current_value
threshold_value
gap = threshold_value - current_value (or max - current for LTV)
CONSTRAINT → SCENARIO TYPE MAPPING:
CREDIT_SCORE_BELOW_MINIMUM → CREDIT_IMPROVEMENT
DTI_EXCEEDS_LIMIT → DEBT_PAYOFF, CO_BORROWER_ADD, LOAN_AMOUNT_REDUCTION
LTV_EXCEEDS_MAXIMUM → DOWN_PAYMENT_INCREASE
INSUFFICIENT_FUNDS_CTC → DOWN_PAYMENT_INCREASE (wait / gift funds)
INSUFFICIENT_RESERVES → WAIT_AND_SEASON (save to reserves)
BANKRUPTCY_WAITING_PERIOD → WAIT_AND_SEASON
FORECLOSURE_WAITING_PERIOD → WAIT_AND_SEASON
PROPERTY_TYPE_INELIGIBLE → PROGRAM_SWITCH (if alternate program allows)
RATE_SUBOPTIMAL → RATE_BUYDOWN
PAYMENT_TOO_HIGH → LOAN_AMOUNT_REDUCTION, RATE_BUYDOWN
INPUTS:
qualifying_credit_score (current)
credit_score_targets = [minimum thresholds for each ineligible program]
COMPUTATION:
For each ineligible program blocked by credit:
score_gap = program_minimum - qualifying_credit_score
target_score = minimum_blocked_program_threshold
score_gap = target_score - qualifying_credit_score
TIMELINE ESTIMATE:
score_gap 1–10 pts: 1–2 months (minor negative item removal or utilization reduction)
score_gap 11–30 pts: 3–6 months (credit utilization paydown, dispute resolution)
score_gap 31–60 pts: 6–12 months (aging of derogatory items, significant paydown)
score_gap 61–100 pts: 12–24 months (major rehabilitation)
score_gap > 100 pts: 24+ months (extended rehabilitation)
SPECIFIC ACTIONS (always include):
IF score_gap ≤ 30 AND credit_util > 30%:
"Pay down revolving balances to below 30% utilization"
estimated_paydown = (current_revolving_balance - (credit_limit × 0.30))
IF derogatory_items > 0:
"Review credit report for errors; dispute inaccuracies"
IF thin_file:
"Consider authorized user status on established account"
ALWAYS: "Do not apply for new credit during qualification period"
OUTPUT:
scenario_type: CREDIT_IMPROVEMENT
current_score: [X]
target_score: [Y]
score_gap: [Z]
timeline_estimate: "[N] months"
estimated_cost: "Low — primarily time and utilization management"
programs_unlocked: [list of programs that become eligible at target score]
composite_score_after: [re-run scoring with target score]
INPUTS:
current_down_payment_amount
property_value
current_ltv = (property_value - current_down) / property_value
ltv_targets = thresholds relevant to the constraint
DSCR max: 80.00%
FHA max: 96.50% (standard)
Conventional: 95%, 90%, 80% (PMI elimination)
For each LTV target:
required_loan = property_value × ltv_target
required_down = property_value - required_loan
additional_down_needed = required_down - current_down_payment_amount
IMPACT:
New LTV → check eligibility gates → new approval_certainty
New PMI/MIP requirement (if LTV crosses threshold)
New payment (smaller loan)
New CTC (higher down payment)
monthly_payment_delta = (current_loan - required_loan) × pmt_factor(rate)
lifetime_mi_delta = new_lifetime_mi - current_lifetime_mi
net_benefit = PV of payment savings + MI savings - additional_down_cost
TIMELINE: Depends on savings rate — not computable without income; flag TIMELINE_BORROWER_DEPENDENT
OUTPUT:
scenario_type: DOWN_PAYMENT_INCREASE
current_ltv: [X]%
target_ltv: [Y]%
additional_down_needed: $[Z]
new_monthly_payment: $[A] (delta: $[B]/month)
new_lifetime_mi: $[C] (savings: $[D])
new_ctc: $[E]
programs_affected: [list]
INPUTS:
current_back_dti
dti_limit (program-specific — lowest relevant limit)
gmi_monthly
monthly_obligations (itemized list from BorrowerProfile)
target_dti = dti_limit (or 43% for general compliance)
COMPUTATION:
current_total_obligations = gmi_monthly × current_back_dti - housing_payment
target_total_obligations = gmi_monthly × target_dti - housing_payment
required_reduction = current_total_obligations - target_total_obligations
PAYOFF PRIORITIZATION:
Sort obligations by balance ÷ monthly_payment (months to payoff)
Recommend the obligation(s) with smallest balance that eliminates enough DTI
For each candidate obligation:
new_dti = (current_obligations - obligation_monthly) / gmi_monthly + housing_ratio
IF new_dti ≤ target_dti: payoff_target = this obligation
IF single payoff insufficient:
Stack payoffs until DTI target met
PAYOFF SOURCES:
Available from: savings, gift funds (check program rules), sale proceeds
OUTPUT:
scenario_type: DEBT_PAYOFF
current_back_dti: [X]%
target_back_dti: [Y]%
recommended_payoffs: [list of specific debts by amount]
total_payoff_amount: $[Z]
new_back_dti: [A]%
programs_unlocked: [list]
monthly_savings: $[B] (reduced obligations)
INPUTS:
current_gmi_monthly
housing_payment (PITIA for the program)
current_back_dti
monthly_obligations
COMPUTATION:
current_all_in = housing_payment + monthly_obligations
target_back_dti = 43% (manual UW) or 45% (DU) or 50% (TOTAL) per program
required_combined_gmi = current_all_in / target_back_dti
co_borrower_income_needed = required_combined_gmi - current_gmi_monthly
IMPACT:
New combined DTI = current_all_in / required_combined_gmi
Verify co-borrower credit score is acceptable (use qualifying_credit_score logic)
NOTE: Co-borrower adds credit obligation — their debts also enter DTI.
adjusted_co_borrower_income = co_borrower_gross_income
adjusted_obligations = current_monthly_obligations + co_borrower_obligations
combined_back_dti = (housing + adjusted_obligations) / (gmi + co_borrower_gmi)
flag CO_BORROWER_OBLIGATIONS_UNKNOWN if co-borrower debt unknown
OUTPUT:
scenario_type: CO_BORROWER_ADD
current_gmi: $[X]/month
co_borrower_income_needed: $[Y]/month (minimum pre-tax)
combined_dti_at_minimum: [Z]%
programs_unlocked: [list]
note: "Co-borrower's own debts will increase DTI — verify income exceeds minimum by cushion"
INPUTS:
current_rate
loan_amount
current_monthly_payment
buydown_target_rates = [current - 0.25%, current - 0.50%, current - 1.00%]
For each buydown target:
points_cost = 1 point = 1% of loan amount per 0.25% rate reduction
(approximate market convention — varies by lender)
buydown_0_25pct = loan_amount × 0.01
buydown_0_50pct = loan_amount × 0.02
buydown_1_00pct = loan_amount × 0.04
new_payment = loan_amount × pmt_factor(buydown_rate)
monthly_savings = current_payment - new_payment
break_even_months = ROUND_UP(points_cost / monthly_savings)
IF break_even_months ≤ 36: buydown_recommended = true
IF break_even_months > 84: buydown_not_recommended = true
OUTPUT per buydown option:
scenario_type: RATE_BUYDOWN
target_rate: [X]%
points_cost: $[Y] ([Z] points)
new_monthly_payment: $[A]
monthly_savings: $[B]
break_even_months: [N]
break_even_label: "[N] months ([M] years [K] months)"
recommended: true | false
INPUTS:
current_loan_amount
current_back_dti
gmi_monthly
dti_limit (binding)
housing_payment_components = tax + insurance + HOA + MI (fixed costs)
rate (current program rate)
COMPUTATION:
fixed_housing = tax + insurance + HOA + MI
target_back_dti = dti_limit
max_total_housing = gmi_monthly × target_back_dti - monthly_obligations
max_pi = max_total_housing - fixed_housing
max_loan = max_pi / pmt_factor(rate)
IF max_loan > 0:
required_price_reduction = current_loan_amount - max_loan
max_purchase_price = max_loan / (1 - down_payment_pct)
note: "Property price must be ≤ $[max_purchase_price] at current income"
ELSE:
max_loan = 0 — borrower cannot qualify at any loan amount on this program/income
OUTPUT:
scenario_type: LOAN_AMOUNT_REDUCTION
current_loan: $[X]
max_loan_at_compliance: $[Y]
required_reduction: $[Z]
max_purchase_price: $[A]
new_monthly_payment: $[B]
new_back_dti: [target_dti]%
Each scenario is scored on two dimensions:
EFFORT SCORE (0–100, lower effort = higher score):
CREDIT_IMPROVEMENT, gap ≤ 20 pts: 80
CREDIT_IMPROVEMENT, gap 21–50 pts: 50
CREDIT_IMPROVEMENT, gap > 50 pts: 20
DOWN_PAYMENT_INCREASE, ≤ $10K: 85
DOWN_PAYMENT_INCREASE, $10K–$30K: 60
DOWN_PAYMENT_INCREASE, > $30K: 30
DEBT_PAYOFF, total ≤ $5K: 90
DEBT_PAYOFF, $5K–$20K: 65
DEBT_PAYOFF, > $20K: 35
CO_BORROWER_ADD: 70 (relationship-dependent)
RATE_BUYDOWN (break-even ≤ 36mo): 75
LOAN_AMOUNT_REDUCTION: 60 (requires finding different property)
WAIT_AND_SEASON, ≤ 12 months: 70
WAIT_AND_SEASON, > 12 months: 25
PROGRAM_SWITCH (already eligible): 95 (just choose the other program)
IMPACT SCORE (0–100, higher impact = higher score):
Based on: composite_score_after - composite_score_before
0–5 pts improvement: 20
6–15 pts: 50
16–25 pts: 75
26+ pts: 95
effort_impact_score = (effort_score × 0.40) + (impact_score × 0.60)
SORT by effort_impact_score descending. Take top 3–5 scenarios.
NOTE: Always include PROGRAM_SWITCH if applicable — it is always the fastest path.
{
"schema_version": "clarity_engine_v1.0",
"skill": "SCENARIO_GENERATION",
"skill_version": "1.0",
"deal_id": "string",
"borrower_id": "string",
"created_at": "ISO 8601 UTC",
"trigger_conditions": [],
"binding_constraints": [],
"scenarios": [
{
"scenario_id": "S1",
"rank": 1,
"scenario_type": "string",
"headline": "string (one sentence: what changes and what it unlocks)",
"effort_score": 0,
"impact_score": 0,
"effort_impact_score": 0.0,
"current_state": {},
"target_state": {},
"required_action": "string",
"required_amount": 0.0,
"timeline_estimate": "string",
"programs_affected": [],
"composite_score_before": 0.0,
"composite_score_after": 0.0,
"monthly_payment_delta": 0.0,
"total_cost_delta": 0.0,
"flags": []
}
],
"scenario_count": 0,
"primary_scenario": "S1",
"primary_scenario_rationale": "string",
"flags": [],
"lineage_trace": {}
}
Binding Constraint:
CONVENTIONAL: INELIGIBLE_DTI
back_dti = 54.88% (conventional limit 45% DU / 43% manual)
DTI_gap = 54.88% - 45.00% = 9.88 percentage points
GMI = $9,150/month
housing_payment = $3,857.30 (PITIA)
monthly_obligations = $1,166.66
Scenario Selection:
The borrower is CURRENTLY APPROVED (VA + FHA eligible). Scenarios target reaching Conventional — the highest-quality, lowest-MI program at this credit profile.
SCENARIO 1 — PROGRAM_SWITCH (VA — already eligible)
effort_score = 95 (no action needed — program already approved)
impact_score: VA composite=87.08 vs current FHA backup=50.09 → delta=37.0 → 95
effort_impact_score = 95×0.40 + 95×0.60 = 95.00
headline: "VA loan is already approved — take it now. $93/month savings vs FHA."
required_action: "Choose VA over FHA — no additional steps required."
timeline: Immediate
programs_affected: [VA → PRIMARY]
composite_before: 50.09 (FHA baseline)
composite_after: 87.08 (VA)
monthly_payment_delta: −$93.02 (VA vs FHA)
SCENARIO 2 — DEBT_PAYOFF (Conventional unlock)
target_back_dti = 45.00% (DU limit)
current_all_in = $3,857.30 + $1,166.66 = $5,023.96
target_total_housing = $9,150 × 0.45 = $4,117.50
max_obligations = $4,117.50 - $3,857.30 = $260.20
required_reduction = $1,166.66 - $260.20 = $906.46/month in obligations
Obligation reduction of $906.46/month:
This likely requires paying off the majority of monthly debt obligations.
At typical consumer debt rates, $906/month in obligations represents ~$18,000–$30,000 in balances.
Specific payoff targets: determined by Constraint Detection flag DEBT_PAYOFF_CANDIDATES
effort_score = 35 ($906/month = significant payoff required)
impact_score: Conventional composite ≈ 63.37 (proximity) → delta vs FHA = 63.37-50.09 = 13.28 → 50
effort_impact_score = 35×0.40 + 50×0.60 = 44.00
headline: "Pay down $906+/month in obligations to unlock Conventional at DTI 45%."
required_amount: $906.46/month obligations eliminated
timeline: Depends on available payoff funds
composite_before: 50.09; composite_after: ~63.37 (if Conventional qualifies)
monthly_payment_delta: −$3,857.30 - -$3,456.85 = −$400.45 vs FHA
note: Conventional PMI cancels at 80% LTV — long-term savings vs FHA life-of-loan MIP
SCENARIO 3 — CO_BORROWER_ADD (Conventional unlock)
required_combined_gmi = $5,023.96 / 0.45 = $11,164.36/month
co_borrower_income_needed = $11,164.36 - $9,150.00 = $2,014.36/month ($24,172/yr minimum)
effort_score = 70
impact_score = 50 (same as Scenario 2 — unlocks Conventional)
effort_impact_score = 70×0.40 + 50×0.60 = 58.00
headline: "Add a co-borrower earning $2,015+/month to reach 45% DTI for Conventional."
required_amount: $2,014.36/month gross income (co-borrower)
timeline: Immediate (if co-borrower available)
note: Co-borrower's own monthly obligations will increase DTI — income must clear minimum by cushion.
Final ScenarioSet (ranked):
S1 (95.00): PROGRAM_SWITCH → VA — take now, $93/month savings, no action needed
S2 (58.00): CO_BORROWER_ADD → $2,015+/month co-borrower income unlocks Conventional
S3 (44.00): DEBT_PAYOFF → eliminate $906/month in obligations for Conventional
Primary scenario: S1 — borrower should take VA now. S2/S3 are for future Conventional access.
FS-01: Vague scenario descriptions
"Improve your credit score" → FORBIDDEN
"Increase credit score 23 points (gap: 640 minimum vs 617 current)" → REQUIRED
All scenarios must include specific numbers, amounts, and timelines.
FS-02: Recommending scenarios that require impossible actions
Never recommend a program switch to an ineligible program as the scenario resolution.
Never recommend credit improvement beyond 100 points as a "quick" fix.
FS-03: Generating scenarios without constraint linkage
Every scenario must link to a specific binding constraint from the ConstraintList.
Orphaned scenarios (not tied to a constraint) must not be included.
FS-04: Omitting the PROGRAM_SWITCH scenario when a better program is already eligible
If the borrower is approved on program A but not B, and B would be better,
PROGRAM_SWITCH to A must always appear as Scenario 1.
FS-05: Over-generating scenarios
Maximum 5 scenarios in a ScenarioSet. More creates decision paralysis.
Rank and prune. The top 3 are mandatory; 4th and 5th are optional value-adds.
FS-06: Ignoring co-borrower debt obligations
When modeling CO_BORROWER_ADD, always flag CO_BORROWER_OBLIGATIONS_UNKNOWN
if co-borrower debt is not provided. Never assume 0 co-borrower obligations.
| Skill | Relationship |
|---|---|
Clarity_Engine_Optimization_SKILL.md | Required input — provides OptimizationResult |
Clarity_Engine_Constraint_Detection_SKILL.md | Required input — provides ConstraintList |
Clarity_Engine_Borrower_Profile_SKILL.md | Required input — provides BorrowerProfile |
Clarity_Engine_Ranking_SKILL.md | Downstream — receives ScenarioSet |
Clarity_Engine_Explanation_SKILL.md | Downstream — narrative for each scenario |
Clarity Engine — Scenario Generation Skill v1.0 | CONFIDENTIAL — PreFi, Inc. / Purpose Technology, Inc. d/b/a Purlend