matchmaking-v2/research/docs/SCOUT_UI_SPEC.md

# Scout UI — Lean Finalization Spec

> Screen-by-screen "what we surface" decisions for the Scout UI, made against what the **engine +
> deployed agents can actually produce** (see `ENGINE_DESIGN.md`, `SIGNAL_AUDIT_V2.md`,
> `agent-capability` evidence). Work happens **in-place in `dashboard-ui/scout`** (no rebuilds).
> Written 2026-06-16.

## Guiding principles
- **Don't fake it; lock it.** Features that are real *later* are shown as a tasteful **"coming soon"
  locked tile**, never with fabricated data. Nothing here is a lie.
- **Personas stay only where backed.** **Mira** = real (resume-builder parsed/tailored an existing
  résumé) → keep. The bubble-journey **"Nova"** is being replaced wholesale (see Configure) → gone.
- Cut the three never-backed claims everywhere: **"live status", "in-network", invented deadlines.**

---

## Summary tab (two states)

### First-time view → **UNCHANGED**
Onboarding doorway (hero + 4-step "how it works" + CTA). Locked as-is — "812 live roles" reads as
*market scale*, not a corpus claim; "Mira" is backed. No edits.

### Returning view (metrics dashboard) → leaned
- **KEEP (producible today):** Streak · Monthly report · Readiness·QX (qscore + assessment) ·
  Matches found · Top match · Salary band · Competition (avg applicants from listings) · Match range/
  distribution · Momentum / Readiness trend (qscore over time) · What your agents did (logged) ·
  **Application funnel** = `Matches → Viewed → Shortlisted → Applied`, **all user-activity** (Viewed =
  jobs the user opened, Shortlisted = saved) · **Your Apply window** (freshness-based urgency from
  listing posting-age, replaces generic "Golden window") · **Your rank** = activity percentile from
  **Scout activity only** (searches/views/saves/applies in the matchmaking DB; "top X% by how much
  you're working your search" — honest engagement, not a quality claim) · Search stage.
- **🔒 LOCK (coming soon):** Expert / human review.
- **CUT:** Search plan ("as you sleep") · Proof-ready · Market value · Response·tracked (no recruiter
  callback) · Warm intros (no referral agent).

---

## Configure tab → ~90% intact (the strongest screen)

| Section | Decision |
|---|---|
| Hero "Here's the search I'd run for you" | ✅ keep |
| Profile summary ("parsed by **Mira**", title/seniority/industry/city/years) | ✅ keep — real (resume-builder + LinkedIn) |
| **"Matching you on N signals"** transparency bar | ✅ keep, **but fix the list** to match `SIGNAL_AUDIT_V2`: keep Role&level + Skills + What-you-value; **Market context is now BACKED via Perplexity** (keep); add verified-LinkedIn / QScore / course-behavior; drop any item with no source |
| "Also matching on · derived" (comp/stage/availability/deal-breakers/dream cos/hide-employer) | ✅ keep — real preference/filter inputs |
| **Video intro** | ✅ **KEEP** — reuse the existing `VideoResumeBuilder.tsx`; persist via interview-service's MinIO blob storage (record → store). Drop the "rides with in-network" copy |
| "What are you after?" (More like this / step up / new) | ✅ keep — **FIT vs STRETCH** core |
| "What matters most?" (pick 2) | ✅ keep — ranking weights |
| "How far should I reach?" (Safe/Balanced/Reach) | ✅ keep — reach band |
| "Work mode" | ✅ keep — hard filter |
| **The must-haves bubble box** ("Fine-tune everything") | ✅ **KEEP the box, swap the engine** → reuse course **`BubblePicker` + `useBubbleField`** (physics: grow-on-like +6 / love +12, live repack). **"Add your own" on EVERY row (crucial)** — esp. **Where/location** (tier-2/3 cities typed → real preferred-location bubble). **AI suggestions via `onGenerateMore` but STRIP the "ai" badge** — untagged, indistinguishable from presets. Replaces `ScoutBubbleJourney`/Nova |
| **Location** (the "Where" row, lives in the bubble box) | ✅ feeds the **ported location-fit logic** (`SIGNAL_AUDIT_V2`): substring city match, Remote→100, Anywhere→open. Add-your-own + that scoring = location finally handled right |
| Footer "Scout never applies without you" | ✅ keep — honest consent |

**Net Configure:** keep almost everything; the only real changes are (1) fix the signal-transparency
list to the true set, (2) reuse `VideoResumeBuilder` for video-intro, (3) replace the bubble journey
with the course bubbler (add-your-own + untagged AI), (4) wire the ported location logic.

---

## Action tab → leaned, with an honest apply flow

**A) Loader** (`JobMatchingLoader`) — **rework copy to the on-demand truth:** *"Looking in 3+ job
boards · Scanning 100+ roles"* → normalize skills → score against your signals → rank. Drop the fake
"812 corpus scan." ("fresh by construction — pulled seconds ago.")

**B) Filter bar** — ✅ keep (the hard filters + active chips + Clear all).

**C) Match card** (`MatchCard`):
| Element | Decision |
|---|---|
| match % + **QX breakdown** | ✅ keep — but it IS **the engine's match breakdown**: the white-box signal dimensions (skill match, experience, **location-fit**, course-behavior, QScore competence, market context). "Why we matched you," powered by the real engine, not gamified QX |
| title · ₹pay · applicants | ✅ keep (from listings) |
| **"Closes in N days"** | ❌ **removed** → "posted Nd ago" (no real deadline data) |
| "+N QX on apply" · "Proof-ready" · "In-network · live status" | ❌ cut |
| "Video intro ✓" | ✅ keep (reuse Video Resume; drop in-network gating) |
| "Warm intro · can refer you" | ❌ cut (no mentor/referral agent) |
| "light on {gap} → 15-min mock / Expert mock / {course}" | ✅ keep (interview/roleplay/course are real) |
| "Why Scout picked this" + tags | ✅ keep — wire to the TRUE signals |

**D) Swipe controls** (Pass / undo / info / Save) — ✅ keep. These emit the **VIEW / SAVE / PASS
events** that feed the funnel + activity rank.

**E) Apply flow (the hand-off) — make it honest and concrete:**
1. **Approve once** — the single consent tap (keep).
2. **Per-job résumé tailoring** — for each saved role, resume-builder tailors the résumé + cover
   letter. **NEW UX: a per-job spinner** ("Tailoring your résumé for {company}…") — this step had no UI.
3. **Auto-apply** — the master-key engine submits (tier-aware: public-ATS/India-ATS = autonomous;
   login-gated = staged handoff).
4. **Result — split, with proof:**
   - ✅ **Applied (auto):** show the **captured confirmation screenshot** per role — *verified, not
     assumed* (the engine already screenshots the success page).
   - ⚠️ **Couldn't auto-apply** (login_required / no_form / failed / spam-flagged): list these with
     **"Apply manually →"** + the live link, so the user finishes them by hand.

**Net Action:** real bones kept (match + engine breakdown + why + mock/course boosts + apply), the
recurring cuts applied (in-network/live-status, +QX framing, warm-intro/referral, add-to-pathway,
deadlines), loader made honest, and the apply flow gains the **resume-tailoring spinner** + **proof
screenshots** + **manual-apply fallback** for failures.

---

## BUILD PROGRESS — as shipped on branch `job-ui-final` (updated 2026-06-17)

Built in-place in `dashboard-ui/scout` (+ `components/job-matching`). Committed/pushed:
`job-ui-final` (head `780e09e`+). All states compile; `/scout` serves clean. The build went
**further than this spec in places** — recorded here so the spec stays the source of truth.
Honesty check: **every divergence is a cut or an improvement; nothing surfaces a claim the engine
can't back** (re-verified against `ENGINE_DESIGN.md`).

**Configure (most changed):**
- ✅ Bubble box swapped to the ported course physics — `components/scout/bubble/{useBubbleField,ScoutBubbleField}`; like/love grow+repack, **add-your-own + untagged "Suggest more"** on taste rows. (`ScoutBubbleJourney` rewired off Nova/`NovaBubbles`.)
- ✅ Location upgraded **beyond spec**: cascading **Country→City** picker (`LocationPicker.tsx`, ported from the old matchmaking `FilterBar` — flags, searchable city, "select country first"). Stored as `"City · Country"`; the deck matcher now scores **city AND country** (`filterSortScoutJobs`). Feeds Tier-A `preferred_locations`.
- ✅ Profile card is now **editable in place** ("Edit details" ↔ "Done") + a **"Fine-tune" orange pill** (header) and **"Fine-tune everything"** (bottom) → the bubble journey. All dropdowns are one shared **searchable `CustomSelect`** (type-your-own → "Use 'X'") with an **"Any"** option that maps to *no constraint* for the engine.
- ✅ **No-resume / nothing-selected state** (NEW, not in original spec): card opens in edit mode, every field defaults to **"Any"**, headline "What are you looking for?", an **"Add a resume to pre-fill"** action (simulated Mira parse). This is the UI face of engine §3.3 (sparse profile → coverage renormalizes, never fabricates). Preview toggle to view both states.
- ⚠️ **DIVERGENCE — "Matching you on N signals" bar: REMOVED** (text-light pass), not "kept + fixed" as spec said. Signals still feed the engine; just not surfaced. *Re-add a 1-line honest version if we want the credibility back.*
- ⚠️ **DIVERGENCE — Video intro: REMOVED** from card + chip (Tier-C, not wired). Spec wanted keep.
- ⚠️ **DIVERGENCE — dream-companies + hide-employer editing dropped** (kept comp/stage/availability/deal-breakers as read-only chips → editable inline).
- ✅ Removed the lame **"Use my résumé instead"** shortcut everywhere.

**Summary:**
- ✅ 9 headline cards (activity-led) + 3 behind "More metrics"; Expert/human review **locked "coming soon"** (Mira/Vera hand-offs stay live).
- ✅ Market signals trimmed to producible set (dropped layoff/funnel/hiring-velocity).
- ⚠️ **DIVERGENCE — Readiness·QX assessment card REMOVED** (+8 QX reward theatre gone). QScore/assessment remain real Tier-B engine signals; "Readiness trend" still in More-metrics. Spec wanted keep.
- ⚠️ **PENDING — "Golden apply window" not yet renamed** to the freshness/posting-age "Apply window" (§6.1).

**Action / match:**
- ✅ Loader honest: `Looking across 3+ job boards · Scanning 100+ live roles · Scoring · Ranking`; **MATCH_SCOPE 812→120**.
- ✅ **Video-intro chip removed** from `MatchCard`.
- ✅ Swipe card **action-bar overlap fixed** — card now renders in normal flow (`AnimatePresence popLayout`), so expanding the QX breakdown grows the page and Pass/Undo/Info/Save stay below it (removed the brittle absolute+ResizeObserver container).
- ⚠️ **DIVERGENCE — Action-tab filter bar + chips + `ScoutFilterSheet`: REMOVED.** Configure is the single source of search criteria; empty deck → "Adjust in Configure". Spec wanted keep.
- 🔧 **PENDING (needs engine):** apply-flow proof screenshots + auto/failed→manual split; per-job resume-tailoring spinner. These wait on engine apply-result statuses.

**Text/polish:** all accented "résumé" → plain **"resume"**; "Pick 2" casing.