Version: 1.0 | Status: Implementation-Ready — Gear 1
Scope: Captures the complete decision lineage from every upstream Clarity Engine skill into a single canonical audit record. Every gate, every computed value, every flag, every rule applied — structured for human review, compliance export, and ML training pipeline ingestion.
Confidential: PreFi, Inc. / Purpose Technology, Inc. d/b/a Purlend
The Audit Trace Skill is the institutional memory of every Clarity Engine run. It answers the question any auditor, borrower, regulator, or data scientist might ask: "Show me exactly how you reached that conclusion, step by step."
This skill does not compute mortgage outcomes. It consolidates, structures, and surfaces the lineage traces emitted by every upstream skill into a single queryable, human-readable, compliance-ready record.
Why audit trace matters for Purlend:
Inputs required:
LineageTrace objects from upstream skills (Borrower Profile, Router, VA, Conv, FHA, DSCR, Optimization, Scenario, Ranking, Overlay)QualResult objectsOverlayAdjustedResultRankedProgramListOutputs produced:
AuditTrace — complete, canonical, structured decision recordAuditSummary — compressed human-readable version (3 tiers: BRIEF / STANDARD / FULL)DecisionNodeMap — every decision point with input → rule → outputComplianceExport — ECOA adverse action readiness, HMDA fieldsMLTrainingRecord — structured JSON for training pipeline
The AuditTrace is organized in layers, matching the Clarity Engine execution order:
LAYER 0: Run Metadata
deal_id, borrower_id, trace_id, created_at, skill_versions
LAYER 1: Borrower Profile
Input normalization decisions, income calculation, credit score selection,
asset verification, property value determination
LAYER 2: Program Router
Gate 1–5 results for each program, queue order, preliminary calculations
LAYER 3: Program Qualification (one sub-trace per program run)
VA: all 14 stages with inputs, computed values, pass/fail at each gate
CONV: all 17 stages
FHA: all 17 stages
DSCR: all 14 stages (if investment property)
LAYER 4: Optimization
Dimension scores, weight application, composite scores, sensitivity
LAYER 5: Scenario Generation
Binding constraints identified, scenarios generated, effort-impact scores
LAYER 6: Ranking
Sort order, tiebreaker application, confidence computation
LAYER 7: Overlay
Overlay flags applied, confidence adjustments, lender guidance
LAYER 8: Synthesis
Final ranked output, Always-Approved state, compliance flags
Stage 1 — Collect and validate all upstream lineage traces
Stage 2 — Assign trace IDs to all decision nodes
Stage 3 — Build the DecisionNodeMap
Stage 4 — Detect deviation nodes (any non-standard path)
Stage 5 — Generate AuditSummary (all three tiers)
Stage 6 — Generate ComplianceExport (ECOA / HMDA)
Stage 7 — Generate MLTrainingRecord
Stage 8 — Emit complete AuditTrace
Every decision point in the Clarity Engine receives a unique trace ID.
FORMAT: [LAYER].[SKILL_CODE].[SEQUENCE].[OUTCOME]
LAYER: L0–L8
SKILL_CODE: BP (Borrower Profile), RT (Router), VA, CV (Conventional),
FH (FHA), DS (DSCR), OP (Optimization), SG (Scenario Gen),
RK (Ranking), OV (Overlay), SY (Synthesis)
SEQUENCE: sequential integer within skill
OUTCOME: P (pass), F (fail), C (conditional), I (informational)
EXAMPLES:
L2.RT.03.P → Router stage 3, pass
L3.VA.06.F → VA stage 6 (residual income), fail
L3.FH.09.C → FHA stage 9 (DSCR ratio), conditional
L4.OP.04.I → Optimization stage 4 scoring, informational
L7.OV.02.P → Overlay stage 2 credit check, pass
TRACE CHAIN:
Each node records its parent node(s) — forming a directed acyclic graph (DAG).
This enables: "which input values led to this outcome?"
For each decision node, record:
node_id: trace ID (see above)
node_type: GATE | COMPUTATION | SCORING | FLAG | OVERRIDE
skill: which skill owns this node
stage: stage number within skill
stage_name: human-readable stage name
inputs: {field_name: value} — all inputs to this decision
rule_applied: human-readable description of the rule
rule_reference: guideline citation (e.g., "HUD 4000.1 Section II.A.1.b")
computed_values: {field_name: value} — all outputs of this decision
outcome: PASS | FAIL | CONDITIONAL | INFORMATIONAL
outcome_reason: one-sentence explanation
parent_nodes: [list of node_ids that fed into this node]
child_nodes: [list of node_ids this node feeds into]
flags_triggered: [list of flag codes]
deviation: false (true if non-standard path)
deviation_reason: null or explanation
NODE TYPE RULES:
GATE: binary pass/fail — affects program eligibility
COMPUTATION: numeric calculation — carries to downstream nodes
SCORING: dimension score or composite — optimization layer only
FLAG: advisory or blocking signal — no binary outcome
OVERRIDE: manual or conditional bypass — always requires human_review = true
A deviation is any decision that departs from the standard optimal path.
DEVIATION TYPES:
INELIGIBLE_PROGRAM: A program failed at a gate — track which gate and why
CONDITIONAL_APPROVAL: AUS downgrade, manual underwrite required, or DSCR < 1.00
CONSTRAINT_CLUSTER: Multiple binding constraints on same program
DATA_INCOMPLETE: Required field was null or estimated
BOUNDARY_VALUE: Input is within 2% of a threshold (LTV, DTI, score)
OVERLAY_DOWNGRADE: Confidence reduced by overlay
SCENARIO_REQUIRED: Always-Approved state is not CURRENTLY_ACHIEVABLE
FOR each deviation:
deviation_id: [trace_id]_DEV_[sequence]
deviation_type: [from list above]
affected_programs: [list]
severity: INFO | WARNING | BLOCKING
resolution: null (INFO/WARNING) or REQUIRED (BLOCKING)
BOUNDARY_VALUE flags are particularly important — they represent:
"The borrower is close enough to a threshold that a small change
would change the outcome. Flag for advisor attention."
Three summary tiers. Always generate all three — output the appropriate tier
based on the requesting context (BRIEF for borrower, FULL for auditor).
TIER 1: BRIEF (borrower-facing, 3–5 sentences)
Structure:
1. What programs were evaluated
2. What the recommendation is and the primary reason
3. What the biggest limitation is (if any)
4. What the next action is (if any)
Language rules:
No jargon (no DTI, LTV, PITIA, LLPA in BRIEF tier)
No negative framing — reframe constraints as actions
Use dollar amounts, not percentages where possible
The word "denied" does not appear
Example:
"We evaluated four loan programs for your home purchase.
The VA loan is your best fit — it requires no down payment and has
the lowest total cost at $3,363/month.
FHA is a strong backup if the VA benefit isn't available.
You're approved and ready to move forward."
TIER 2: STANDARD (advisor-facing, structured bullet format)
Structure:
- Programs evaluated: [list with status]
- Primary recommendation: [program, score, confidence]
- Key metrics: payment, CTC, MI, rate
- Binding constraints: [list with resolution]
- Scenarios available: [count and type]
- Next steps: [ordered action list]
Language: Professional, specific, no hedging
TIER 3: FULL (auditor/compliance/ML — complete trace)
Structure:
- All Layer 0–8 decision nodes
- All computed values with intermediate steps
- All flags with trigger conditions
- All deviation records
- Compliance export fields
Language: Technical, precise, all values stated to full precision
ECOA ADVERSE ACTION NOTICE READINESS:
Triggered when: any program has qualification_status = INELIGIBLE_*
Required elements (Regulation B / 12 CFR Part 202):
1. Specific reasons for adverse action (up to 4 reasons)
2. ECOA notice language
3. Credit score disclosure (if credit-based decision)
REASON MAPPING (constraint → ECOA reason statement):
DTI_EXCEEDS_LIMIT → "Debt obligations too high in relation to income"
LTV_EXCEEDS_MAXIMUM → "Insufficient down payment for loan amount requested"
CREDIT_SCORE_BELOW_MINIMUM → "Credit score below required minimum"
INSUFFICIENT_FUNDS_CTC → "Insufficient funds for closing"
WAITING_PERIOD_ACTIVE → "Insufficient time elapsed since [event]"
PROPERTY_TYPE_INELIGIBLE → "Property type not eligible for requested program"
CREDIT SCORE DISCLOSURE (required when credit score used):
score: qualifying_credit_score
score_range: [score_model_min, score_model_max] (300–850 for FICO)
score_date: [pull date]
score_factors: [top 4 negative factors from credit report — if available]
disclosure_text: [FCRA 615(a) language]
ECOA_NOTICE_TEXT (standard — always include):
"The federal Equal Credit Opportunity Act prohibits creditors from
discriminating against credit applicants on the basis of race, color,
religion, national origin, sex, marital status, age (provided the
applicant has the capacity to enter into a binding contract), because
all or part of the applicant's income derives from any public assistance
program, or because the applicant has in good faith exercised any right
under the Consumer Credit Protection Act."
HMDA FIELDS (for eligible transactions):
action_taken: 1=originated, 2=approved not accepted, 3=denied,
4=withdrawn, 5=incomplete, 6=purchased, 7=preapproval denied,
8=preapproval approved not accepted
loan_type: 1=conventional, 2=FHA, 3=VA, 4=USDA/RHS
loan_purpose: 1=purchase, 2=improvement, 31=refi, 32=cash-out refi, 4=other
lien_status: 1=first lien, 2=subordinate
applicant_income: GMI rounded to nearest thousand
loan_amount: loan amount rounded to nearest thousand
NOTE: HMDA race/ethnicity/gender fields collected by lender from borrower —
NOT populated by Clarity Engine (fair lending firewall)
Every Audit Trace generates a structured ML training record.
This feeds the Clarity Engine's continuous improvement loop.
TRAINING RECORD STRUCTURE:
{
"record_id": "[deal_id]_[trace_id]",
"created_at": "ISO 8601",
"outcome": "APPROVED | INELIGIBLE | CONDITIONAL",
"programs_eligible": ["VA", "FHA", ...],
"primary_program": "VA",
"composite_scores": {"VA": 87.08, "FHA": 50.09},
"confidence_final": {"VA": 0.95, "FHA": 0.83},
"binding_constraints": [...],
"scenario_count": 3,
"always_approved_tier": "TIER_1_NOW | TIER_2_ONE_ACTION | ...",
"borrower_goal": "GOAL_BALANCED",
"key_features": {
"qualifying_credit_score": 698,
"back_dti_primary": 47.37,
"ltv_primary": 1.0215,
"funds_pct_property": 0.066,
"veteran": true,
"property_state": "CA",
"property_type": "SFR"
},
"flags_triggered": [...],
"deviation_count": 1,
"data_quality_score": 0.95
}
DATA QUALITY SCORE:
Starts at 1.00. Deducted per missing/estimated field:
−0.05 per estimated value (e.g., tax estimate used)
−0.10 per null required field (e.g., income not verified)
−0.15 per unverified asset
data_quality_score = CLAMP(1.00 − deductions, 0.00, 1.00)
High quality scores → more reliable training signal
Low quality scores → record flagged for review before training use
{
"schema_version": "clarity_engine_v1.0",
"skill": "AUDIT_TRACE",
"skill_version": "1.0",
"trace_id": "string (UUID)",
"deal_id": "string",
"borrower_id": "string",
"created_at": "ISO 8601 UTC",
"run_duration_ms": 0,
"skill_versions_used": {
"borrower_profile": "1.2",
"program_router": "1.0",
"va_module": "1.0",
"conventional": "1.0",
"fha": "1.0",
"dscr": "1.0",
"optimization": "1.0",
"scenario_generation": "1.0",
"ranking": "1.0",
"overlay": "1.0",
"audit_trace": "1.0"
},
"layers": {
"L0_metadata": {},
"L1_borrower_profile": { "node_count": 0, "nodes": [] },
"L2_program_router": { "node_count": 0, "nodes": [] },
"L3_program_qualification": {
"VA": { "node_count": 0, "nodes": [], "final_status": "string" },
"CONVENTIONAL": { "node_count": 0, "nodes": [], "final_status": "string" },
"FHA": { "node_count": 0, "nodes": [], "final_status": "string" },
"DSCR": { "node_count": 0, "nodes": [], "final_status": "string" }
},
"L4_optimization": { "node_count": 0, "nodes": [] },
"L5_scenario_generation": { "node_count": 0, "nodes": [] },
"L6_ranking": { "node_count": 0, "nodes": [] },
"L7_overlay": { "node_count": 0, "nodes": [] },
"L8_synthesis": { "node_count": 0, "nodes": [] }
},
"decision_node_map": {
"total_nodes": 0,
"gate_nodes": 0,
"computation_nodes": 0,
"scoring_nodes": 0,
"flag_nodes": 0,
"override_nodes": 0
},
"deviations": {
"total_deviations": 0,
"blocking_deviations": 0,
"deviations": []
},
"audit_summary": {
"brief": "string",
"standard": {},
"full": "see layers above"
},
"compliance_export": {
"ecoa_adverse_action_required": false,
"adverse_action_reasons": [],
"credit_score_disclosure": {},
"ecoa_notice_text": "string",
"hmda_fields": {}
},
"ml_training_record": {},
"flags": ["HMDA_REPORTABLE", "ANTI_STEERING_COMPLIANT"],
"data_quality_score": 0.00
}
Run context:
deal_id: WEB-2026-001
Programs evaluated: VA (QUALIFIED), FHA (QUALIFIED_TOTAL_ACCEPT), CONV (INELIGIBLE_DTI)
Primary recommendation: VA
Property state: CA
trace_id: TRC-WEB-001
Key Decision Nodes (selected):
L2.RT.01.P Router Gate 1 — Webb: PRIMARY occupancy
input: occupancy_type=PRIMARY
rule: All programs eligible for primary. DSCR requires INVESTMENT.
output: VA=eligible, FHA=eligible, CONV=eligible, DSCR=ineligible
flags: [DSCR_INELIGIBLE_OCCUPANCY]
L2.RT.03.P Router Gate 3 — Credit score
input: qualifying_credit_score=698
rule: VA≥580✓, FHA≥580✓, CONV≥620✓, DSCR≥640 (N/A — DSCR already out)
output: all three pass
L3.CV.17.F Conventional Stage 17 — DTI determination
input: back_end_dti=54.88%, limit=45% (DU) / 43% (manual)
rule: Fannie Mae SEL 2021-08 — back DTI 45% DU, 43% manual
output: INELIGIBLE_DTI
flags: [DTI_EXCEEDS_CONVENTIONAL_LIMIT]
deviation: true — program blocked by DTI
L3.VA.09.P VA Stage 9 — Residual income
input: residual_income=1,602.67, threshold=1,000 (CA, 4-person household)
rule: VA Lenders Handbook Chapter 4 Table
output: QUALIFIED — residual income exceeds threshold
flags: [VA_RESIDUAL_INCOME_MET]
L4.OP.04.I Optimization — VA composite score
input: pay=54.54, mi=86.95, ctc=88.00, cert=90.00, qb=15
rule: composite = pay×0.35 + mi×0.20 + ctc×0.20 + cert×0.20 + qb
output: composite=87.08
computed_values: {payment_score:54.54, mi_score:86.95, ctc_score:88.00, cert_score:90.00}
L7.OV.05.C Overlay Stage 5 — California community property
input: property_state=CA, non_borrowing_spouse_debt=UNKNOWN
rule: CA is community property state — non-borrowing spouse debt must be reviewed
output: CONDITIONAL — data review required
confidence_adjustment: -0.03
flags: [COMMUNITY_PROPERTY_STATE, NON_BORROWING_SPOUSE_DEBT_REVIEW]
Deviations:
DEV-001:
deviation_type: INELIGIBLE_PROGRAM
affected_programs: [CONVENTIONAL]
severity: WARNING
cause_node: L3.CV.17.F
cause: back_end_dti=54.88% exceeds 45% DU limit by 9.88 ppts
resolution: See Scenario S2 (DEBT_PAYOFF $906/mo) or S3 (CO_BORROWER $2,015/mo)
boundary_value: false (gap > 5 ppts)
DEV-002:
deviation_type: DATA_INCOMPLETE
affected_programs: [VA, FHA]
severity: INFO
cause: CA non-borrowing spouse debt not provided
resolution: Collect non-borrowing spouse debt disclosure before submission
ECOA Export:
ecoa_adverse_action_required: true (CONVENTIONAL INELIGIBLE)
adverse_action_reasons:
[1] "Debt obligations too high in relation to income" (back DTI 54.88%)
credit_score_disclosure:
score: 698
score_range: [300, 850]
note: "Credit score disclosure required per FCRA 615(a)"
Audit Summary — BRIEF tier:
"We evaluated VA, FHA, and Conventional loans for your home purchase.
The VA loan is your best option — no down payment required, $3,364/month,
and it uses your military benefit to its full potential.
FHA is a strong backup at $3,457/month.
Conventional is not available at your current debt level, but can be unlocked
by reducing monthly obligations by about $906."
ML Training Record:
outcome: APPROVED (VA + FHA)
programs_eligible: [VA, FHA]
composite_scores: {VA: 87.08, FHA: 50.09}
confidence_final: {VA: 0.95, FHA: 0.83}
binding_constraints: [DTI_EXCEEDS_CONVENTIONAL_LIMIT]
always_approved_tier: TIER_1_NOW
key_features:
credit_score: 698, back_dti: 47.37 (VA), ltv: 1.0215 (VA)
veteran: true, state: CA, property_type: SFR
data_quality_score: 0.90 (−0.05 CA tax estimate; −0.05 non-borrowing spouse unknown)
FA-01: Generating audit traces without consuming upstream lineage traces
The Audit Trace Skill must receive actual lineage trace objects from upstream skills.
Never reconstruct a trace from QualResult outputs alone — the decision path,
not just the outcome, is required.
FA-02: Including race, ethnicity, gender, or national origin in the ML training record
Fair lending firewall: these fields are never collected or stored by Clarity Engine.
The ML training record must not include any protected class data.
flag FAIR_LENDING_FIREWALL_ACTIVE on all ML records.
FA-03: Using BRIEF tier language in compliance exports
ECOA adverse action reasons must be precise and regulatory-compliant.
Never substitute borrower-friendly paraphrasing for the required legal language.
FA-04: Omitting ECOA adverse action export when any program is INELIGIBLE
If ANY program in the evaluation reached INELIGIBLE status, ECOA export is required.
This applies even if the borrower qualifies on other programs.
FA-05: Assigning the same trace ID to two different decision nodes
Trace IDs are globally unique within a run. Use the FORMAT specified in Stage 2.
Duplicate trace IDs destroy the DAG structure and make lineage unresolvable.
| Skill | Relationship |
|---|---|
| All upstream skills | Input — provide LineageTrace objects |
Clarity_Engine_Always_Approved_SKILL.md | Downstream — consumes AuditTrace |
Clarity_Engine_Explanation_SKILL.md | Downstream — Brief/Standard summaries feed explanation |
Clarity Engine — Audit Trace Skill v1.0 | CONFIDENTIAL — PreFi, Inc. / Purpose Technology, Inc. d/b/a Purlend