How Transform My Role works under the hood
The pipeline that turns a job posting into a personal transformation plan — ingest modes, the extraction adapter, the mapping resolver and its confidence tiers, the gap-synthesis primitive, and the plan-package envelope.
The pipeline at a glance
Transform My Role chains five existing RPF primitives. Ingest (URL fetch / paste text / file upload, all routed through the same in-memory pipeline). Extraction (the action-statement extraction agent, parameterised for job-posting shape). Mapping (resolve candidates to existing RPF Roles / Items / IUs by slug and IRI-shape match, with a future-ready counterpart picked from the role_archetype chain). Gap synthesis (the same computeProfileGap() as the org-level Profile Gap surface, applied to a transient current-state Profile derived from the matched candidates). Plan assembly (wraps the Phase-4 personaPlan envelope with transform-specific metadata).
URL fetch (default)
Server-side fetch with a 10-second timeout, max 3 redirects, max 5 MB response, content-type allowlist (text/html, application/pdf, application/xhtml+xml, text/plain), robots.txt respected (1-hour cache), conservative no-crawl host list. The URL is consumed once and never persisted — not even the host. User-Agent identifies this surface explicitly.
Paste text (tickbox-gated)
Paste the full description. The text crosses into the extraction agent only after the rights-acknowledgement tickbox is ticked (per the M18.2.1 privacy/legal review's symmetric posture — paste is functionally identical to upload). The pasted text is never persisted.
Upload (tickbox-gated)
PDF, plain text, or Markdown, up to 5 MB. Bytes route through an in-memory ephemeral processing path with a 60-minute hard-cap TTL. No SMC source-material row is created — the SMC catalog cannot see personal-transform uploads by construction.
Extraction adapter
We wrap the action-statement extraction agent with a job-posting-shaped prompt template. The adapter receives parsed Markdown only — the raw URL or upload bytes never reach the agent. The agent returns a structured candidate envelope: { roleCandidates, items, informationUses, jurisdictionHint, confidence }. The confidence here is the agent's self-reported extraction confidence — distinct from the mapping confidence below.
Mapping resolver and confidence tiers
The mapping resolver takes the candidate envelope and resolves to existing RPF entities by slug + IRI-shape match. If the matched Role is itself a future-ready Role (via role_archetype = 'future_ready'), it is the counterpart. Otherwise we walk the succeeds_role_id chain to find the canonical future-ready counterpart in the user's jurisdiction. Each candidate carries a confidence in [0,1] and a tier label.
High confidence. The plan is rendered with the matched canonical Role as the future-ready counterpart. The gap section is computed and displayed.
Mid confidence. The plan is rendered with the suggested canonical Role, but the UI marks the match as suggested. The agent panel's chip set includes a "verify before relying on it" question.
Best-effort only. The plan still renders, but the no-match section surfaces with the runner-up role, a rationale, and a sponsorship CTA pointing at the body one-pager. The gap section is omitted unless a future-ready counterpart can still be identified.
Gap synthesis (reuses the Profile Gap math)
We synthesise a transient "current-state" Profile from the matched candidates (in memory, never persisted), then run it against the resolved canonical future-ready Profile using the same computeProfileGap() function as the org-level Profile Gap surface (M18.1.1). The output is the same ProfileGap shape — ΔIRI, ΔICI, missing/extra items, IU coverage changes, material substitutions — wrapped in the transform plan envelope.
Plan-package assembly
The plan-package assembler wraps the Phase-4 personaPlan envelope with transform-specific metadata (sourceMode, jurisdictionResolved, mappingConfidence, generatedAt, version). It emits the same downstream shape — so Assessor.io's existing personaPlan template consumer reads a transform plan with no changes. HTML, PDF (print-stylesheet via Cmd-P), and Assessor.io template are the three export formats.
Change notifications
When you save a transformation plan you can opt in to change notifications. A daily job checks whether the canonical future-ready Role behind each of your saved plans has been updated. When one or more have, you receive a single digest email — grouped, so several changed plans arrive as one message rather than several. Only changes dated after you subscribed count, so turning notifications on never triggers a 'nothing changed' email.
Notifications are opt-in and registered-user only. Archived plans never generate a notice. Every digest carries a one-click unsubscribe link that stops all change notifications at once; you can re-enable them per plan from your saved plans. The digest is sent to your account email and names only your own saved-plan titles back to you — see the privacy page.
Edge cases
- If the extraction agent yields no role candidates, the page surfaces the no-candidates empty state with a CTA pointing at this methodology page. The audit row records outcome=extract_fail.
- If no future-ready counterpart exists in the user's jurisdiction (the canonical is queued behind a sponsoring body), the page surfaces the no-future-ready empty state with a sponsorship CTA pointing at the body one-pager.
- If the only candidate has mapping confidence < 0.4, the plan renders with the candidate marked as Low confidence and the agent panel surfaces a "verify before relying on it" chip.
- Sessions are short-TTL (≤ 60 minutes in line with the upload-blob TTL). A session-not-found state on a deep link sends the user back to the landing form; re-ingest produces a fresh session.
- If gap synthesis fails (rare — usually a malformed canonical Profile), the plan renders with the mapping summary and a noGap placeholder. The audit row records the partial outcome.
When to trust vs verify
Treat Matched-tier plans as a solid starting draft — the canonical match is high confidence and the gap math is deterministic. Treat Suggested-tier plans as a draft to verify before sharing with a learner; open the agent panel and step through "How was the role mapped?" and "Why is this missing?". Treat Low-confidence plans as a hypothesis: the plan still renders, but the sponsorship empty state hints that this discipline + jurisdiction needs a canonical sponsor before the math becomes reliable.
Privacy posture
The privacy posture is documented separately. Key headlines for the methodology view: the raw job description, the URL, and any uploaded bytes never cross into the agent context — only the parsed structured candidates do. The audit row carries no content-shaped fields. Anonymous sessions are in-memory only.
Stability tier
The transform plan package wraps the Phase-4 personaPlan shape. The wrapper is at stability tier beta; breaking shape changes will bump the schemaVersion in the package envelope and be called out in the change log.
