Skip to main content

​
AI Overview rework — domain model and build plan

Status: planned (Aug 2026). Decided in a grilling session with Kevin; supersedes the original post-confirm design that was discussed in the same session (see Decision log).

​
What the AI Overview is (final shape)

A pre-selection strategy coach for the operator. Generated on demand, after underwriting completes and before product selection, from a card on the /contact Overview tab placed directly above the Product Decisions panel. Its job is cross-product strategy sequencing the engine does not do — e.g. “remove the inquiries not tied to open accounts first, then use the term-loan proceeds to pay down these three cards, which lifts utilization under 30% and materially improves the 0% card outcome” — ending with an explicit handoff: select these products in Product Decisions and begin the funding workflow. Benchmark profile: high score, heavy encumbrance (many inquiries, large paydowns). Golden test case: contact RY9HEzVryPbYyMNbpmQW, location isqlsHX3ljyFgKYAxPTQ (Toan Nguyen) — great score/pre-approval, 10 inquiries in 12 months, $20k+ paydowns.

​
Trigger and billing contract

  • Manual generate button, available to every location. No settings. The button is the consent for the charge; the tooltip states the price. No operator toggle, no admin kill-switch, no schema change. The admin aiOverviewEnabled flag stays retired-in-place (it gates nothing today and continues to gate nothing).
  • Credit pull charges creditPullPrice (5default)atpulltime.AIOverviewcharges‘aiOverviewSurcharge‘(5 default) at pull time. AI Overview charges `aiOverviewSurcharge` (2 default) at click time, on cache miss only. These are and remain fully separate charges (tests/billing.test.ts locks this in). There is no combined $7 charge.
  • Cache hits are free; the $2 buys the overview for that file’s data-state permanently. Deliberate Regenerate clicks are each billed. Admin/internal locations (creditPullPrice === 0) generate free.
  • Never auto-generated. Not at underwriting time, not on auto (webhook) pulls. Auto-generation would charge without operator intent and would resurrect the need for a per-location opt-in setting. If demand appears later, an opt-in “auto-generate on manual pulls” location setting is an additive follow-up.
  • If the charge succeeds but the LLM fails, the charge is not auto-refunded (existing behavior); the card shows a non-blocking error with a retry.

​
Roles and responsibilities at every step

​
Output contract (PR 2)

Dual-section output, stored on underwritingResults.aiOverview (widened with optional fields for backward compatibility with cached rows; cache namespace bumped so old-format caches regenerate naturally — same pattern as borderline-v1):
  1. Operator section: the strategy narrative — sequenced plan with per-account dollar amounts, which inquiries are plausibly removable, how term-loan proceeds interact with card-stacking outcomes, and the product-selection recommendation. Steps split by owner (client lane / operator lane).
  2. Client-safe summary: relayable verbatim or via the funding plan email later. Says “CRM”, never GHL; never mentions 7 Figures (existing sanitizer extended).
Prompt inputs to add (engine computes these but never sends them today): per-account balances/limits, per-account paydownRecommendations dollar amounts, the inquiry list with open-account association (may need a small deterministic matching helper so the AI cites facts rather than guessing), decline/status codes, and the estimated ranges per track. The engine remains the source of truth: the model may only cite dollar amounts and thresholds present in its input. The computeDataHash inputs must grow in lockstep with the prompt inputs, or stale overviews will survive data changes. Borderline files (requiresManualReview) keep their separate skeptical prompt.

​
Build phases (one branch + PR each, cut from origin/main)

  1. PR 1 — cleanup: delete the dead $5 + $2 wallet pre-check in the new-lead webhook and lib/webhooks/auto-credit-pull-core.ts (it checks 7whilethesystemonlyevercharges7 while the system only ever charges 5); update billing tests; land this doc.
  2. PR 2 — strategy-coach prompt: new system prompt + enriched inputs + dual output schema + cache-namespace bump + Toan Nguyen golden fixture (read-only data pull into a test fixture). Consider a model bump from openai/gpt-4o-mini and a higher token ceiling for the longer plan. Verifiable without UI: iterate against the golden fixture and the existing /api/ai-overview/generate route directly. Lands before the UI so the card is designed once, against the final output contract, instead of being built for the old shape and reworked.
  3. PR 3 — placement + generate flow: AI Overview card on the /contact Overview tab above Product Decisions, with ungenerated (explains value + price), generating, error-with-retry, generated, and Outdated states. Renders the dual output contract from PR 2; reuses the existing /api/ai-overview/generate charge path unchanged. Note: AiOverviewSection currently renders only on surfaces that never receive contactId/locationId (why the feature is invisible today); the contact page uses CreditReportsView, which never included it.
Deferred (explicitly out of scope now): machine-readable action codes with one-click buttons; closer talk-track; post-confirm divergence note (“selection contradicts recommendation”); opt-in auto-generate setting.

​
Decision log (grilling session, Aug 6 2026)

  • Post-confirm trigger with “Confirm and generate AI Overview” button — superseded: the overview’s job moved from execution plan to pre-selection strategy coach after the Toan Nguyen example showed the highest-value output is sequencing advice that informs product selection.
  • Operator toggle in Settings + admin kill-switch — superseded: with a manual button, the click is the consent; no settings are needed.
  • “AI Overview settings” letting operators choose generation timing — rejected: two prompts/caches/placements for one feature; pick one moment.
  • Auto-generate at underwriting time — rejected: charges without operator intent, effectively the $7-per-pull model; also bills dead/duplicate/webhook files.
  • Confirm always succeeds independently of AI billing — retained (now trivially true since Confirm no longer touches AI).
  • Dual output (operator + client-safe) — retained.
  • Stale-on-data-change with paid regenerate, never auto-charge — retained.
  • No AI Overview on auto pulls — retained.