---
estimated_steps: 4
estimated_files: 4
skills_used:
  - react-best-practices
  - test
---

# T03: Wire ranked Gmail suggestions into the job workspace UI

**Slice:** S01 — Smarter Gmail import and matching
**Milestone:** M001

## Description

Deliver the user-facing part of the slice in the actual job workspace. The Correspondence tab should stop acting like a generic Gmail search box and instead open with job-aware ranked suggestions from the backend, explain why each candidate is relevant, let the user override with manual search when needed, and refresh the job-linked correspondence view after import.

## Steps

1. Update `job-tracker-ui/src/types.ts` to reflect the new backend candidate contract and enriched correspondence metadata from T01 and T02.
2. Pass job context from `job-tracker-ui/src/components/JobDetailsDialog.tsx` into `job-tracker-ui/src/components/Correspondence.tsx` so the Gmail tab can request job-aware suggestions without duplicating the job fetch.
3. Refactor `job-tracker-ui/src/components/Correspondence.tsx` to consume the backend-ranked suggestions, show thread/message match reasons and import state, keep manual Gmail query override/search available, and refresh the rendered correspondence list after successful imports.
4. Add `job-tracker-ui/src/correspondence-gmail-import.test.tsx` covering ranked suggestion rendering, reason/confidence display, thread vs single-message import actions, and refresh after import.

## Must-Haves

- [ ] The Gmail tab opens on job-aware ranked suggestions instead of using `scoreMessage(...)` as the primary intelligence.
- [ ] The UI still supports manual Gmail searching as a fallback override, but it no longer depends on freeform query heuristics for the core experience.
- [ ] The React test proves the user can see ranked suggestions and that importing updates the same job’s correspondence surface.

## Verification

- `CI=true npm --prefix job-tracker-ui test -- --watch=false --runTestsByPath src/correspondence-gmail-import.test.tsx`
- Manually inspect the dialog to confirm ranked reasons/import state are visible and the correspondence list refreshes after import.

## Observability Impact

- Signals added/changed: visible match reasons/confidence/import state in the Gmail tab and clearer import success/duplicate feedback toasts.
- How a future agent inspects this: read `job-tracker-ui/src/correspondence-gmail-import.test.tsx` and open the Correspondence dialog in the running app.
- Failure state exposed: the UI should distinguish no matches, already-imported candidates, loading states, and import failures instead of collapsing them into a generic empty list.

## Inputs

- `job-tracker-ui/src/components/JobDetailsDialog.tsx` — host dialog that already owns the job record.
- `job-tracker-ui/src/components/Correspondence.tsx` — current Gmail import UI with client-side ranking.
- `job-tracker-ui/src/types.ts` — frontend API contracts.
- `JobTrackerApi/Controllers/GmailController.cs` — T01/T02 backend Gmail candidate and import contract.

## Expected Output

- `job-tracker-ui/src/components/JobDetailsDialog.tsx` — passes job context into the correspondence tab.
- `job-tracker-ui/src/components/Correspondence.tsx` — renders job-aware Gmail suggestions and refreshed import behavior.
- `job-tracker-ui/src/types.ts` — matches the updated backend contract.
- `job-tracker-ui/src/correspondence-gmail-import.test.tsx` — proves the UI flow end to end at component level.