MOPC-Portal/docs/superpowers/specs/2026-06-01-mentorship-comms-and-welcome-email-design.md

Mentorship Communications & Welcome/Reminder Email — Design

• Date: 2026-06-01
• Status: Approved (pending spec review)
• Author: Matt + Claude
• Topic: Make mentor↔team contact effortless and add a re-sendable, instructional "welcome/reminder" email for mentoring rounds.

Context

MOPC already has a working mentorship feature:

• Two-way in-app messaging exists (MentorMessage model; WorkspaceChat + MentorChat components; trpc.mentor.sendMessage / getMessages and trpc.applicant.sendMentorMessage / getMentorMessages). Mentors are auto-notified when applicants write.
• Contact emails are already visible: mentors see each team member's email as individual mailto: links (src/app/(mentor)/mentor/projects/[id]/page.tsx); applicants see their mentor's name+email (src/app/(applicant)/applicant/mentor/page.tsx) and teammates' emails (src/app/(applicant)/applicant/team/page.tsx).
• Round-open auto emails already fire: flipping a MENTORING round draft→active sends a coalesced "you've been assigned to N projects" email to each mentor (getMentorBulkAssignmentTemplate / sendMentorBulkAssignmentEmail) and a "meet your mentors" intro to each team (getTeamMentorIntroductionTemplate / sendTeamMentorIntroductionEmail). These are one-time, gated by MentorAssignment.notificationSentAt and MentorAssignment.teamIntroducedAt (src/server/services/round-engine.ts).

Two gaps remain:

1. There is no single "email all team members" affordance for mentors — only per-person mailto: links.
2. The round-open emails don't explain how to use the mentorship features, and there is no way to re-send them later as a reminder.

Goals

• A mentor can email their whole team in one click (opens their mail client, all members in To:).
• The round-open assignment emails are upgraded in place to include (a) the relevant contact emails and (b) how-to-use-the-mentorship-features instructions.
• An admin can re-send that same email on demand (a "welcome/reminder" blast) to all mentors + teams in a mentoring round, with an optional custom note.
• The admin can preview the exact email (mentor + team versions) before sending.

Non-goals

• No new in-app messaging surfaces (the chat already exists).
• No new email-provider infrastructure (reuse src/lib/email.ts wrapper, helpers, throttling, NotificationLog).
• No mentors-only / teams-only targeting toggle for v1 — the reminder sends to both audiences. (Can be added later if needed.)

Feature 1 — Mentor "Email all team members" button

• Location: src/app/(mentor)/mentor/projects/[id]/page.tsx, in the existing Team Members card, alongside the per-member mailto: links.
• Behavior: builds mailto:<comma-joined emails>?subject=... with all active team members in To: (per decision), subject pre-filled MOPC Mentorship — {project title}. Clicking opens the mentor's default mail app.
• Edge cases: filter out blank/missing emails defensively (schema makes User.email required+non-null, but be safe); hide the button when the team has zero emailable members.
• Scope: pure client-side; no backend changes.

Feature 2 — Unified mentorship welcome/reminder email

Decision: upgrade in place, don't duplicate

Rather than send a second email on round-open, the existing two templates are enhanced so they carry the instructions + contact emails. The same template code is reused by both trigger paths below. One email per audience; one source of truth.

Content — Mentor version (coalesced per mentor, across their projects in the round)

• Greeting by mentor name.
• Optional custom note (rendered in an info box near the top) — only present on the manual reminder path.
• For each assigned project: project title (linked) + the team members listed with name + email.
• "How to mentor on MOPC" instructions block: where the workspace chat lives, file sharing, the mentor dashboard.
• CTA → Mentor Dashboard.

Content — Team version (per project)

• Greeting by recipient name.
• Optional custom note (info box) — manual path only.
• The assigned mentor(s) listed with name + email.
• The team's own members listed with email (per decision: include teammates too).
• "How to work with your mentor" instructions block: where the in-app chat is, how to reach the mentor, what to expect.
• CTA → mentoring page.

Both reuse getEmailWrapper() and existing helpers (sectionTitle, paragraph, ctaButton, infoBox, escapeHtml) for consistent branding.

Trigger path A — auto on round-open (existing flow, upgraded content)

• src/server/services/round-engine.ts draft→active flow keeps its one-time semantics (notificationSentAt / teamIntroducedAt gating) and coalescing.
• It now passes the additional data the upgraded templates need: team-member name+email for the mentor email, and mentor name+email + teammate emails for the team email.
• No custom note on this path.

Trigger path B — manual reminder button (admin, on demand)

• New adminProcedure: mentor.sendMentorshipWelcome({ roundId, customNote?: string }).
  • Resolves all current active assignments for the round (droppedAt: null) → groups by mentor → sends mentor emails; resolves all projects with assignments → sends team emails to all members.
  • Ignores notificationSentAt / teamIntroducedAt (deliberate re-send). Does not mutate those flags.
  • Throttled + fire-and-forget like existing bulk sends; writes NotificationLog rows + a DecisionAuditLog/audit entry.
  • Returns counts: { mentorCount, teamMemberCount, teamCount } for the success toast.

Preview

• New query: mentor.previewMentorshipWelcome({ roundId, customNote?: string }) → { mentor: { subject, html }, team: { subject, html } }.
  • Calls the same template functions used by the real send.
  • Picks a representative recipient: first mentor with assignments + first project/team in the round. If the round has none yet, returns clearly-labeled sample-data output so the layout is still previewable.
• Rendered in the send dialog inside a sandboxed <iframe srcDoc={html}> (isolates email CSS from the app), with Mentor / Team sub-tabs. The custom-note textarea updates the preview live (debounced).

Admin UI

• New component src/components/admin/round/send-mentorship-welcome-button.tsx:
  • Lives in the round detail page's Notifications section (src/app/(admin)/admin/rounds/[roundId]/page.tsx, near NotifyAdvancedButton / NotifyRejectedButton / BulkInviteButton), rendered only when the round is MENTORING.
  • Opens a dialog: recipient summary ("N mentors · M team members across K teams"), optional custom-note textarea, live Preview (Mentor/Team tabs), and a Send button with confirmation.

Files touched

File	Change
src/app/(mentor)/mentor/projects/[id]/page.tsx	Add "Email all team members" button (mailto, all in To:)
src/lib/email.ts	Enhance getMentorBulkAssignmentTemplate + getTeamMentorIntroductionTemplate (contacts, instructions, optional customNote); update sendMentorBulkAssignmentEmail / sendTeamMentorIntroductionEmail signatures + all call sites
src/server/services/round-engine.ts	Pass team-member/mentor emails into upgraded templates on round-open
src/server/routers/mentor.ts	New sendMentorshipWelcome (adminProcedure) + previewMentorshipWelcome (adminProcedure query)
src/components/admin/round/send-mentorship-welcome-button.tsx (new)	Dialog: counts, custom note, live iframe preview, send
src/app/(admin)/admin/rounds/[roundId]/page.tsx	Wire the button into the Notifications section, gated to mentoring rounds

Implementation ordering note

Build the templates first and render both to standalone .html files (and/or screenshots) for copy review before wiring the send path — gives an early visual check with zero throwaway work.

Testing

• Template unit tests (src/lib/email.ts fns return { subject, html, text }, easy to assert): mentor email contains each team member's email + instructions block; team email contains mentor email(s) + teammate emails + instructions; custom note appears when passed, absent when not.
• tRPC test for sendMentorshipWelcome on a seeded mentoring round: correct recipient resolution and returned counts; does not flip the one-time flags.
• tRPC test for previewMentorshipWelcome: returns non-empty mentor + team HTML for a seeded round; sample-data fallback for an empty round.

Decisions (resolved during brainstorming)

1. Upgrade existing intro emails in place (single source of truth), reused by both auto-open and the manual reminder; fallback would have been a standalone manual-only blast.
2. Tailored content per audience (mentor vs team), with contact emails embedded in the relevant spot.
3. Manual reminder: fixed branded template + optional custom note.
4. "Email all" button: all members in To:.
5. Team email includes both the mentor's email and teammates' emails.
6. Manual reminder sends to both audiences (no per-audience toggle in v1).
7. Preview via an in-app button (live, real-data, iframe) rather than pasted static HTML.