docs/requirements-curator-streak-chat-flow.md

Requirements: Curator Streak Chat Flow — Service Handoff & Preview UX

Date: 2026-06-15
Status: Draft — pending stakeholder review
Repos: growqr-backend, growqr-dashboard
Branch: staging-rosh (VPS staging)
Priority: P0 — main blocker for staging user testing

---

1. Goal

When a user clicks a daily/weekly streak or progress suggestion in the GrowQR dashboard, the system must guide them through a focused, coherent conversation that produces a service preview CTA — not a blank setup screen — so they can immediately start the intended service (interview, roleplay, resume, etc.) with sensible defaults derived from their onboarding profile and goals.

What good looks like: a user who clicks "practice behavioral interview" gets asked at most one clarifying question, then sees a clear card with a button that says "Open interview preview" and lands directly on a preview screen with the role, round type, and difficulty already set.

---

2. Scope — What This Covers

In Scope	Out of Scope
Streak/weekly progress component chat modal	TalkToMe chat route/component
Curator backend prompt behavior	New AI model selection
Interview preview handoff	Resume parser internals
Roleplay preview handoff	Q Score calculation engine
Service CTA card rendering	Social branding / courses
Prompt externalization	Billing/subscription flows
3-suggestion daily task model	Admin dashboards
30/60-day growth plan coherence	Full mission actor rewrite

---

3. Stakeholder Experience — The Exact Flow

3.1 User Lands on Dashboard

The user sees:

• Streak progress (e.g., "5-day streak 🔥")
• Weekly progress with 3 suggestions
• Each suggestion has a title, subtitle, and an actionable CTA

The suggestions are derived from the user's onboarding answers (ICP, goals, blockers) and current Q Score / readiness state.

3.2 User Clicks a Suggestion

Example: "Practice behavioral interview — Product Manager"

A chat modal opens. The assistant header shows:

• Avatar + "Daily Mission" label
• Subtask title: "Practice behavioral interview"
• Service name: "Interview Coach"

3.3 First Turn

The curator should not ask a generic "What do you want to do?" question.

It should say something like:

"I’ll set up a 5-minute behavioral interview preview for you. What role should I focus on — or is Product Manager still your target?"

If the onboarding already captured the role, it should skip the question entirely and proceed directly to the preview card.

3.4 User Answers (or Skips)

• User types: "Product Manager" (or just hits Enter if already known)
• Assistant: "Got it. Preparing your preview now."

3.5 Preview CTA Card Appears

A card appears in the chat with:

• Eyebrow: INTERVIEW PREVIEW
• Title: "Your mock interview is ready"
• Details: Role · Round · Difficulty · Duration
• Button: "Open interview preview" (or "Open roleplay preview")
• Secondary link: "Change settings" (opens setup with params pre-filled)

3.6 User Clicks the CTA

The user is routed to:

/agents/interview/preview?role=Product+Manager&type=behavioral&difficulty=medium&duration=5&source=curator-v1&curatorTaskId=...

The preview page loads with the session already configured. The user can:

• Start the interview immediately
• Request question changes
• Go back to chat

3.7 Roleplay Equivalent

Same flow, but for roleplay:

"I’ll set up a salary negotiation practice. What scenario should we rehearse?"

Then CTA card → /agents/roleplay/preview?scenario=... or equivalent builder route with pre-filled params.

---

4. Acceptance Criteria — What "Finish" Looks Like

4.1 Backend Acceptance Criteria

#	Criteria	How to Verify
B1	Curator prompt is externalized to a markdown/txt file	cat prompts/curator/daily-retention-system.md returns the prompt
B2	Interview handoff returns preview route, not setup	/v1/curator/chat response includes handoff.actionRoute containing /agents/interview/preview
B3	Roleplay handoff returns preview route, not setup	Same as B2, but for roleplay
B4	Status is handoff_ready when service context is sufficient	statusUpdate.status === "handoff_ready" after one answer for known role
B5	No infinite questioning — max 1 clarifying question per service task	Log review: assistant never asks same question twice
B6	Default params are sensible: type=behavioral, difficulty=medium, duration=5	Preview loads without user needing to configure
B7	Route includes onboarding-derived role when available	role param is pre-filled from user profile
B8	Curator does not leak internal routes in chat text	No /agents/... URLs in reply field
B9	Service handoff works for Resume (workspace), Q Score (review), Pathways (report)	Each returns correct route with pre-filled context
B10	Build passes on VPS	npm run typecheck and npm run build succeed on staging-rosh

4.2 Frontend Acceptance Criteria

#	Criteria	How to Verify
F1	Streak chat shows service preview CTA card reliably	Click interview suggestion → card appears within 2 turns
F2	CTA card is visually distinct and action-oriented	Card has eyebrow, title, details grid, and primary button
F3	CTA persists after subtask is marked complete	Even in "completed" footer state, the card remains visible
F4	Button copy is service-specific	Interview: "Open interview preview"; Roleplay: "Open roleplay preview"; Resume: "Open resume workspace"
F5	Clicking CTA navigates to correct preview route	Browser URL matches /agents/interview/preview?... or /agents/roleplay/preview?...
F6	Preview page loads with pre-filled params	Interview preview shows role, type, difficulty without user re-entering
F7	No regression to TalkToMe, home feed, or other dashboard pages	Smoke test: dashboard, talk-to-me, missions, settings all load
F8	Build passes on VPS	npm run build succeeds on staging-rosh
F9	Mobile: chat modal and CTA card are usable	Test on mobile viewport: card readable, button tappable
F10	Loading state is clear and non-blocking	"Preparing your preview..." shown instead of generic spinner

4.3 Product Coherence Criteria

#	Criteria	How to Verify
P1	Every task connects back to user's stated goal	Chat copy references user's target role or goal from onboarding
P2	30/60-day plan framing is visible	Suggestion labels include week/day context (e.g., "Week 2 — Day 3")
P3	Tasks follow the 3-suggestion model: Measurement + Proof + Practice	Daily suggestions show one of each category
P4	Streak is meaningful — not just a counter	Completing a task shows progress toward a goal, not just +1 day
P5	User can see why this task matters	Assistant explains: "This builds your interview readiness signal, which improves your Q Score."

---

5. Non-Functional Requirements

Requirement	Target
Curator chat response time	< 3s end-to-end (backend + frontend)
Preview page load time	< 2s after CTA click
Build time on VPS	< 5 minutes per repo
Downtime during deploy	Zero — rolling restart via Docker Compose
Prompt hot-reload	Possible without code redeploy (external file)
Browser compatibility	Chrome, Safari, Firefox latest 2 versions

---

6. Edge Cases & Error Handling

Scenario	Expected Behavior
User gives vague answer	Assistant asks ONE follow-up, then shows preview card with best guess
User has no onboarding role	Assistant asks "What role are you targeting?" — answer generates preview
Service is temporarily down	Assistant shows "Service is warming up — try again in a moment" instead of broken link
User clicks CTA but preview fails	Preview page shows friendly error with "Go back to chat" button
User refreshes dashboard mid-chat	Chat state is lost — acceptable for MVP; later: conversation persistence
User is on mobile	Modal is full-screen, CTA card is thumb-friendly, no horizontal scroll
User has multiple active missions	Curator picks the most relevant mission context for the task
User is a new Day 1 user	Suggestions are simpler: Q Score baseline, Resume upload, Warm-up interview

---

7. Success Metrics

Once deployed to staging, we will measure:

Metric	Baseline	Target
Interview preview CTA visibility rate	0% (broken)	100% when interview task is active
Roleplay preview CTA visibility rate	0% (broken)	100% when roleplay task is active
User reaches preview page after CTA click	N/A	> 90% of clicks
Avg chat turns to preview	N/A	≤ 2 turns
Chat abandonment rate	N/A	< 20%
Build pass rate	N/A	100%
Staging smoke test pass	N/A	100% of test cases

---

8. Dependencies

Dependency	Status	Owner
Interview service preview page	✅ Exists	Interview service team
Roleplay service preview page	⚠️ Needs verification	Roleplay service team
Backend curator routes	✅ Exists	Backend team
Dashboard streak component	✅ Exists	Dashboard team
Onboarding → ICP mapping	✅ Exists	Product (docs)
30-day plan examples	✅ Exists	Product (docs)
VPS staging environment	✅ Running	DevOps

---

9. Open Questions

#	Question	Impact
Q1	Does roleplay have a true /preview route, or should we use /setup with pre-filled params?	Determines route generation in backend
Q2	Should resume handoff go to /agents/resume list or directly to editor?	UX flow
Q3	Should Q Score handoff go to /analytics or /agents/qscore?	Route decision
Q4	Do we want the assistant to stream tokens, or is JSON response acceptable for MVP?	Scope / time
Q5	Should the curator chat be its own separate route from TalkToMe, or share the conversation actor?	Architecture

---

10. Definition of Done

This requirement is finished when:

1. ✅ All backend acceptance criteria (B1–B10) pass on staging
2. ✅ All frontend acceptance criteria (F1–F10) pass on staging
3. ✅ All product coherence criteria (P1–P5) are verified by stakeholder
4. ✅ Staging VPS is stable — no crashes, no 500s, no broken routes
5. ✅ User can click a streak suggestion → chat → preview CTA → preview page → start service, in under 5 interactions
6. ✅ Prompt file is externalized and editable without code redeploy
7. ✅ Changes are committed to staging-rosh on both repos
8. ✅ Staging smoke test passes for all 6 test cases (Section 4)

---

11. Related Documents

• docs/curator-icp-task-subtask-playbook.md — ICP taxonomy and task libraries
• docs/curator-icp-comprehensive-playbook.md — Full service definitions and 30-day plans
• docs/curator-30day-examples-by-icp.md — Copy-pasteable 30-day plans, chat flows, prompt templates
• docs/staging-vps-service-deployment-runbook.md — VPS deployment procedures

---

12. Sign-off

Role	Name	Status
Product Owner	Rosh	Pending review
Backend Lead	—	Pending assignment
Frontend Lead	—	Pending assignment
QA / Staging	—	Pending test execution

---

End of requirements document