Feedback session UX: research + propose flow for the always-visible feedback widget

[s-annam]

Context

From the 2026-08-27 Intern Weekly sync: the feedback widget (FeedbackPanel.tsx) was recently changed to render at all times post-parse instead of only in specific situations. The star rating → email/comment/refinement flow works, but we haven't done real UX thinking on the session itself — when it shows, how intrusive it feels across a visit, and whether the flow after a 5-star vs. a 1-star rating should diverge.

Current implementation for reference:

• src/components/features/FeedbackPanel.tsx — the panel itself. Render-state machine: full (first two mounts) → compact (quiet inline star strip after that) → done (once submitted). Driven by two localStorage flags (ocv_feedback_seen, ocv_feedback_submitted) via usePersistentFlag/usePersistentCounter.
• Fires a single feedback_submitted PostHog event (src/lib/analytics.ts) — anonymous unless the user opts in with an email.
• Rendered inside Result.tsx, directly under the score card.

Problem

We don't have a strong opinion yet on whether the current visible-always behavior is actually the right session design — it was a quick change, not a researched one. Things worth interrogating:

• Does showing it on every single mount (even before "compact" kicks in) feel naggy on a repeat visit in the same session?
• Should the flow branch by rating — e.g. a low rating should probably route toward "what went wrong" free text before anything else, where a high rating could skip straight to the GitHub-star CTA?
• Is localStorage-only state the right memory model, or should "seen"/"submitted" reset per résumé rather than per browser?
• Any accessibility/focus concerns with a panel that appears unprompted post-parse.

Some starting ideas — not a spec, just angles worth checking:

• A lighter first touch (e.g. just the star row, no card chrome) that only expands into the full form once a rating is picked, rather than showing the full amber Card immediately.
• Branching copy/flow by rating value instead of one static form for every rating.
• Consider whether "session" should mean per-résumé-parse rather than the current seen-count-across-mounts model.

What to do

This is intentionally open-ended — we don't have enough detail yet to hand over a fixed spec. First task is not implementation:

1. Look at the current FeedbackPanel behavior in the running app (both full and compact states, and the post-submit thank-you state).
2. Do a short pass of UI/UX research — comparable feedback-widget patterns elsewhere are fair game — and form your own opinion on what should change and why.
3. Update this issue with your findings and a proposed plan (what changes, why, and roughly how big). Don't open a PR yet.
4. Tag @s-annam for review once the plan is written up — we'll discuss and finalize scope together before any code gets written.

Not in scope (yet)

• Changing the feedback_submitted event shape/analytics pipeline.
• Anything about the "further refinement flow" downstream of a submission — flag it in your writeup if you think it needs its own issue, but don't fold it into this one.

[Samhit21]

Research pass + proposal

Headline first: the premise moved after the sync. FeedbackPanel.tsx no longer exists. It was retired in #900 / #903 (9d521a1, "replace inline panel with milestone-triggered FeedbackDialog"), which landed after the 2026-08-27 Intern Weekly. Everything this issue describes — always-visible post-parse, the full → compact → done machine, ocv_feedback_seen — describes the component that was deleted.

So I researched what's actually on main, and three of the five things this issue asks us to interrogate are already answered. The useful output is therefore: what's closed, what's genuinely still open, and what the new design introduced that nobody has looked at yet.

A note on method: I read the implementation rather than driving the running app, because the component named in step 1 isn't there to look at and the behaviour is fully determined by the state machine quoted below. Happy to do a live pass if you want the visual read too.

---

What's on main today

Surface	FeedbackDialog — a real Dialog (native showModal(), browser focus trap), not an inline panel
Step 1	Bare star row. Picking a star routes immediately, no "next" click
Step 2	4–5★ → FeedbackPositiveStep (OSS mission line, GitHub-star CTA, optional note + email opt-in) 1–3★ → FeedbackConstructiveStep ("Tell us what went wrong or what you'd change", optional note + email opt-in)
Step 3	Terminal thanks step with a focused aria-live region. Never auto-dismisses
Auto trigger	A résumé export (PDF or Markdown, never the audit report) arms it; it opens when ExportDialog closes
Ambient trigger	[★ Feedback] button in ParsedHeader
Memory	ocv_feedback_dialog_seen (counter), ocv_feedback_submitted (flag) — both localStorage, per browser

---

Answered by #900 — no work needed

1. "Does showing it on every mount feel naggy?" Moot. It doesn't render post-parse at all any more.
2. "Should the flow branch by rating?" Done, exactly as proposed — handleRate routes value >= 4 ? "positive" : "constructive", and the high-rating branch is where the GitHub-star CTA lives.
3. "A lighter first touch that only expands once a rating is picked." Done — Step 1 is a bare star row and routes on selection.

Still open, and worth deciding

4. The automatic prompt is a hard lifetime cap, and an ambient click burns it.

notifyResumeExported bails on seenCount > 0, and openDialog() increments that counter on any open — including the ambient button. Consequences:

• Dismiss the prompt once, ever → never automatically asked again on that browser.
• Click [★ Feedback] out of curiosity, close it → the automatic trigger is permanently dead.

There is no cooldown, only a lifetime cap. That's a defensible anti-nag stance and it's the opposite failure from the one this issue was filed about, but it was inherited from the #900 implementation rather than chosen. For a product actively recruiting tester feedback it's probably too quiet. Industry guidance is a global cooldown, not a permanent lock (Refiner).

5. Export is the rarest success moment in the funnel.

The only automatic trigger is a résumé download. A user who drops a PDF, reads their score, fixes three bullets and leaves is never asked — and that's a large fraction of sessions. The score card is the product's actual value moment; export is several steps past it. "Task, then ask" is right, but which task is the open question.

6. The auto-opening modal is the one part that runs against the strongest available guidance.

NN/g's User-Feedback Requests is direct about this: ask after task completion (✓ we do), keep an always-available tab as backup (✓ the ambient button), but it "strongly discourages modal popups" and prefers a contextual prompt that doesn't obstruct. We currently open a native modal with a browser focus trap, unprompted, immediately after the user dismissed a different modal.

That also answers the issue's accessibility question, and the answer got worse, not better, with #900. The old concern was "a panel appears unprompted below the fold" (mild). The new one is "a focus-trapping dialog appears unprompted and takes keyboard focus off whatever the user was doing" — for a screen-reader or keyboard user that's a genuine interruption, not a visual one. The in-dialog focus handling is careful (the thanks step is focused and aria-live); it's the arrival that's the problem.

Worth noting the two-moment notifyResumeExported / notifyExportClosed dance exists solely to avoid stacking two native modals. That complexity is a symptom of the modal choice, not a bug.

7. Per-browser vs per-résumé memory is completely untouched.

This issue's question 3 is exactly as open as it was. Both flags are per-browser, so a tester who parses five different résumés is asked once, ever. My read: per-browser is right for submitted (asking a second time after someone already wrote in is spam) and wrong for the trigger — "I have a new résumé and a new result" is a genuinely new experience to rate.

---

Proposal

Roughly in value order. My recommendation is A + B only for this issue; C and D are worth doing but are separable.

A. Replace the auto-opening modal with a non-modal nudge. — small–medium
Keep the milestone trigger and keep the dialog, but have the milestone surface an inline, dismissible prompt (the star row plus one line) near the export/score area rather than seizing focus. Clicking a star opens the full dialog — user-initiated, so the modal is fine at that point. Removes the a11y interruption, removes the modal-stacking problem, and probably lets notifyExportClosed collapse back into notifyResumeExported.

B. Swap the lifetime cap for a cooldown, and stop letting the ambient button burn the trigger. — small
Track ambient opens separately from prompt impressions, and gate the auto-trigger on "not shown in the last N days / not shown for this parse" instead of "never shown". Concretely: keep ocv_feedback_submitted as the permanent kill switch, and make ocv_feedback_dialog_seen a timestamp rather than a counter.

C. Reconsider the milestone. — small to change, needs a decision
Candidates beyond export: first successful edit committed, or N seconds on a result with a score rendered. Needs a product call on which moment we actually want rated — I don't think an intern should pick this unilaterally.

D. Make the trigger per-parse, keep submitted per-browser. — small
Falls out of B nearly for free if the cooldown key incorporates the parseKey the autosave already derives.

---

Flagging for its own issue, per "not in scope"

A dismissed rating is lost entirely. If someone picks 2★ and closes without writing anything, nothing is recorded. That's the strongest signal we have — a low rating — discarded from precisely the users least likely to fill in a free-text box. Firing the rating on selection and treating the note as an enrichment would fix it, but that changes the feedback_submitted event shape, which this issue puts out of scope. I'd open a separate issue; say the word and I'll write it up.

---

@s-annam — over to you. The main thing I'd like a steer on before any code: is the near-silence deliberate? #900 moved us from "always visible" to "at most one automatic ask per browser, ever, and only if you export". This issue was filed about the first problem; we may have overshot into the second. B is the cheap correction, A is the one I think is actually right.

Also worth confirming: this issue's body should probably be updated to reference FeedbackDialog, so the next person reading it isn't sent looking for a deleted file.