Mentorship matching

The mentorship matching surface pairs active members with potential mentors inside the same organization. The matching is automated — a similarity score computed from skills, work history, and certifications — but the actual mentorship is human. Members request, mentors accept, and the platform then steps out of the way.

This page is the admin orientation: what the engine is doing, how members and alumni land in the pool of candidates, what the four match states mean, and what configuration knobs exist (spoiler: very few — this is intentionally an opinionated feature).

Who can use this

Mentorship is primarily a member-facing surface — the default workflow is mentee-requests, mentor-accepts-or-declines. As of v0.63.35, national and regional admins also have direct overrides: a cross-mentee admin view at /org/mentorship with manual pair and unpair actions. Day-to-day, the member-driven flow stays in charge; admin overrides are for relocations, misassignments, and onboarding orgs with legacy mentor records to import.

What the matching engine does

When a member opens the Mentorship page, the platform looks at their own profile data and scores every potential mentor in the same organization. The score is a number between 0 and 1, displayed as a percentage (74% match, 91% match, and so on).

The score is the sum of four components:

Component	Weight	What it measures
Skill overlap	0.4	How many skills you and the mentor share, divided by the size of your combined skill set
Industry overlap	0.3	How many industries (drawn from work history) you share
Certification overlap	0.2	Shared certifications
Base bonus	0.1	A flat bonus for any mentor with any enrichment data at all

On top of that, two small bonuses can nudge the score:

• Embedding similarity (up to +0.1) — if both you and the mentor have AI profile embeddings, the cosine similarity of those embeddings adds a fraction of a point. This catches affinities that pure tag-matching misses: similar career trajectory, similar phrasing in profile narratives.
• Willing to mentor (+0.05) — members who have explicitly toggled "I'm willing to mentor" on their profile get a small score bump.

The total is capped at 1.0 (100%). Matches with a score of 0.0 are dropped from the list entirely.

What "shared skills" actually means

Skill matching is set intersection on the lowercase name. "python" and "Python" match; "ML" and "machine learning" do not. There is no taxonomy and no synonyms — two members with identical career paths but different vocabulary will not match well.

The lever you have as an admin is the Profile completeness configuration — it determines what fields members are nudged to fill out. Encouraging consistent vocabulary (perhaps via custom fields with choice lists for skill categories) sits in your wheelhouse.

Who lands in the candidate pool

For each member, the platform builds the candidate set from two sources, then de-duplicates:

1. Alumni members — anyone in the org whose membership status is active alumni or lifetime alumni. Alumni surface as mentors regardless of whether they have work history filled out.
2. Members with work history — anyone in the org (any active status) with at least one work-history entry. Gives current undergrads access to peer mentors a few years ahead of them.

The requesting user is always excluded. Mentorship is org-scoped — no cross-org matching today. A mentor with no enrichment data still appears (the 0.1 base bonus), but ranks at the bottom unless they've opted in via "willing to mentor."

Suggested mentors grid with match-percentage badges and reason chips.

The four match states

Every member-mentor pair, once it appears in the system, has one of four states. The progression is one-way except for the rare re-request scenario.

State	What it means	Who sees what
Suggested	The score-and-suggest engine surfaced this pair. No one has acted.	Visible to the mentee in their suggestions grid. The mentor sees nothing.
Requested	The mentee clicked "Request Mentor" with an optional message.	Shows in the mentee's Pending section ("waiting for response"). The mentor sees an incoming request with Accept / Decline buttons.
Accepted	The mentor clicked Accept.	Both see the match on their respective "Your Matches" section. The platform considers them matched.
Declined	The mentor clicked Decline.	The pair drops out of the active list. The mentee can re-request later, but no notification fires.

The four states are durable — once a match is Accepted, it stays Accepted until someone removes it manually. There is no "completed mentorship" state; mentorships are open-ended.

Re-requesting a declined match

If a mentor declined a match request and the mentee tries again later (different context, new message), the platform updates the existing record: status flips back to Requested, the new message replaces the old one, and the response timestamp clears. The mentor sees a fresh request to act on.

What admins can do (v0.63.35+)

Open /org/mentorship as a national or regional admin (or platform admin). Non-admins continue to fall through to the member-facing chapter view — they see no behavior change. The admin page surfaces:

Cross-mentee match list

A filter bar plus a table of every match in your admin scope:

• National admin — every match in your organization.
• Regional admin — matches where the mentor's chapter is in your region.
• Platform admin — every match across every org.

Filters: status (Accepted / Requested / Declined / Terminated), mentor email, mentee email, date range (since / until).

Manual pair (POST /api/members/admin/mentor-matches/pair/)

The Pair manually dialog lets you create a match directly — useful for relocations ("Mentor A moved to a different chapter, take over Mentee B's mentorship"), legacy data imports, or any case where the suggest-and-request flow doesn't fit.

• The created match lands as ACCEPTED immediately with is_manual=True.
• You can attach an admin note (free text — recorded on the match) explaining why the pair was manual.
• Refuses self-pair (mentor and mentee can't be the same membership) and cross-org pair (mentor and mentee must share an org). Duplicate active match → 409.

Un-pair (POST /api/members/admin/mentor-matches/<id>/unpair/)

Click Unpair on any active match. The match transitions to TERMINATED (a new status added v0.63.35) and an AuditLog row is emitted with the optional reason you provide. The mentee can re-engage the suggest-and-request flow with a new mentor.

What admins still cannot do

• Adjust matching weights (0.4 skill, 0.3 industry, 0.2 cert) — platform-wide constants. The lever is profile completeness — see Profile completeness configuration.
• Scope mentorship to a chapter or region. Matching is org-wide. A chapter at School A may match with an alumna at School B if they're in the same national org.

What admins should encourage

To make matching useful for an organization, the most impactful things org admins can do are upstream of the matching engine itself.

• Drive profile completeness. The matching engine is only as good as the data. Run a profile completion nudge campaign — see Profile completeness configuration — and explain to members that fuller profiles produce better suggestions.
• Promote LinkedIn import. Members can import work history and skills from LinkedIn via OAuth. Much faster than manual entry, which means more members in the candidate pool with real data.
• Set the "willing to mentor" expectation for alumni. Alumni who opt in get a +0.05 score bump and surface with a "Willing to mentor" reason chip. Frame this as a low-effort way for alumni to stay engaged with chapter members.
• Communicate that this is suggestion, not assignment. A match at 94% is a starting point for a conversation — the mentor decides whether to accept, and either party can ignore a low-quality match.

What members see, briefly

Members hit the Mentorship page from the chapter or org sidebar. They see three sections:

1. Your Matches — accepted mentorships, with a short list of reason chips per match.
2. Pending — incoming requests (if they're being asked to mentor) and outgoing requests (if they're waiting on a mentor's response).
3. Suggested Mentors — the ranked list of potential mentors, with a "Request Mentor" button on each card.

Members write an optional intro message when requesting which the mentor sees on the Accept/Decline screen. This is the single most important input to mentor accept rates.

a pending mentor request card showing the mentee's message and Accept / Decline buttons

Module dependencies

Mentorship is a member-enrichment feature; it does not require a separate module license. It benefits from two adjacent surfaces:

• AI Services (optional) — when configured, the embedding-similarity bonus comes into play. Without it, matching falls back to deterministic skills + industry + certification math.
• Alumni (optional) — when enabled, alumni members can opt into a richer mentor profile (bio, availability, max mentees, industries, career fields). The alumni mentor list overlaps with the matching engine but is browsed differently.

Related

• Profile completeness configuration — the lever for improving match quality
• Alumni directory and privacy — alumni mentor profile, opt-in availability, and privacy settings
• AI Services content scope — turn embeddings on or off for member content
• Permissions matrix

Last verified against v0.63.39 (2026-06-26). Admin pair / unpair / cross-mentee visibility shipped v0.63.35.