Reading a role diff
How computeRoleDiff() compares two roles category-by-category, the A/B convention, what each change category means, and the difference between the in-builder Diff tab and the standalone diff route.
A role diff is the structured difference between two roles: profile edges added or removed, profile classification changes, IRI/ICI shifts, and flow-stage reorders. It is the transformation artefact in RPF — when you see what's different between today's and tomorrow's role, you see what to learn, what to teach, and what to procure.
Three audiences read the diff differently. Professional bodies read it as evidence of what "future-ready" actually means in practice. Org leaders read it as the gap their roles need to close. Practitioners read it as the curriculum they need to walk.
What is a role diff?
The role diff is a pure function over two published roles, A and B. It returns a structured RoleDiff package with five sections: profile edges (added / removed / changed-classification / IRI shift / ICI shift) and flow stages (added / removed / reordered). It does not return prose; it returns categorised structured data the UI renders.
Like the profile gap (M18.1), the diff is computed, not authored. There is no "diff editor". The diff is a live read over both roles, recomputed every time either side changes.
The A/B convention
A is the role you opened the diff from; B is the comparison target (typically A's successor, or set via ?vs=<slug>). Visually, A renders on the left in slate tones; B renders on the right in emerald tones. Green tones mean "added on B / increased toward B"; amber tones mean "removed / decreased."
The subject role — usually the legacy or hybrid one. Renders on the left side of the diff. Slate tones match the archetype-badge palette for legacy.
The comparison target — usually the future-ready successor. Renders on the right side of the diff. Emerald tones match the archetype-badge palette for future-ready.
Change categories
Added profile attachments
Profiles attached to B but not to A. Each row shows the classification (core / primary / supporting). "Added" means the future-ready role expects competence in a profile the legacy role didn't require.
Removed profile attachments
Profiles attached to A but not to B. "Removed" means a competence the legacy role required is no longer central to the future-ready role — often a workflow that has been automated or delegated.
Profile reclassifications
Profiles present on both sides where the classification changed (e.g. core → primary). The change category captures the shift in centrality of a profile within the role, even when both sides carry it.
IRI shift
Per-profile-edge IRI delta (B − A), summed into iriShiftTotal. A positive shift means the future-ready role demands more information across the profile; a negative shift means less. IRI ranges 0–3 per profile per role.
ICI shift
Per-profile-edge ICI delta (B − A), summed into iciShiftTotal. A positive shift means the future-ready role demands more competency depth (a higher cognitive / execution bar). ICI ranges 0–3 per profile per role.
Flow stage reorders
Flow stages present on both sides where the ordinal position changed, plus stages added or removed. A reorder typically signals a flow restructuring — e.g. "design coordination" moving earlier in the lifecycle.
The canonical journey
- 1Open a role detail page — the page shows the archetype badge and the agent panel. If the role has a successor set, the diff is one tab click (in the builder) or one route hop away.
- 2Open the diff: either the Diff tab in the role builder (if you're an admin authoring the role) or /[lang]/roles/[slug]/diff (the standalone read-only route). Both render the same RoleDiffView component over the same RoleDiff package.
- 3Read the summary bar first — added / removed / reclassified / IRI shift / ICI shift / flow reorders. The six numbers tell you the diff's shape in one glance.
- 4Drill into the per-category sections — added profiles (green), removed profiles (amber), reclassifications, IRI/ICI shift table, flow reorders. The agent chips below the view resolve to curated explanations grounded in the same categories.
- 5If the comparison target needs adjusting — say you want to compare against a sibling future-ready role in another jurisdiction — pass ?vs=<slug> on the standalone route. The Diff tab in the builder uses the role's own successor pointer.
Two surfaces, one engine
In-builder Diff tab
The Diff tab inside the role builder (LeftPane) shows the same diff as the standalone route, but with authoring affordances: clicking a row may jump you to the relevant builder section, and the agent first-run hint is shared with the standalone route via a single dismissal key so the tour only runs once across both surfaces. The Diff tab replaced the prior Compare tab in M18.3.3c.
Standalone /[lang]/roles/[slug]/diff route
The standalone route is a read-only server component, statically cacheable, and the canonical link to share when someone wants to see the diff without entering the builder. It accepts ?vs=<other-slug> to override the comparison target, and renders the agent panel + first-run hint inline.
Known limitations
- The diff is role-vs-role, not role-vs-many. Multi-role comparison views are deferred to a later phase.
- The diff reflects what is published. Drafts on either side are not in the comparison.
- Item-level (action-statement-level) diff is not yet surfaced — the role diff stops at the profile-edge granularity. Profile gap (M18.1) provides the item-level view between the two profiles attached to the roles.
- Auto-fix ("copy this profile edge into A") is intentionally not provided. Role updates go through the role-converse proposal flow so they pick up validation + agent-grounded review.
