Role Intelligence Report

The Role Intelligence Report helps HR advisory and recruiting-service teams review unclear client role descriptions before search, job-description cleanup, or advisory recommendations begin.

There are two current evaluation patterns:

a consultant-readable report format assembled from documented Job Analyze outputs;
a Customer Grounding controlled-beta report generated through POST /api/v1/grounding/role-intelligence/reports when the Runtime API Key contract allows it.

The first pattern is not a separate endpoint or finalized API contract. The grounded route adds tenant-scoped customer evidence, source references, and a decision trace.

What It Is

A Role Intelligence Report is a structured second read on a role description.

It translates current AvelinLabs workforce intelligence outputs into a consultant-readable format that can support a human review conversation with a client. The goal is to make role clarity, evidence, ambiguity, and next questions visible without asking the advisor to inspect raw JSON.

Why It Is Different

The report does not hide an interpretation behind polished prose. It keeps evidence, confidence, uncertainty, and review guidance visible. When Customer Grounding is used, source and trace references can show how approved customer knowledge influenced the grounded result.

Why Role Intake Is Hard

Client role intake is often messy. A single role description can combine responsibilities from customer success, operations, business analysis, support coordination, retention, process documentation, and reporting.

That ambiguity matters because it can affect:

how the role is explained to the client;
whether the job description is specific enough;
what skills and outcomes should be emphasized;
when a recruiter, consultant, or advisor should ask for clarification.

What AvelinLabs Extracts

Current Avelin outputs can help a reviewer inspect:

O*NET-grounded occupation alignment;
ranked occupation or role-family candidates;
skill evidence and job signals visible in the text;
confidence, trust, uncertainty, ambiguity, and weak-signal fields;
decision-support routing cues for human review;
plain-English explanation fields where available;
customer evidence, source references, review flags, and a decision trace when the grounded route is used.

These signals are intended to support human review and product workflows. They should not be treated as final truth.

Example: Client Success Operations Lead

Consider this role intake:

Our client needs someone to improve onboarding, coordinate support handoffs, analyze customer usage data, document processes, work with sales and product teams, and identify opportunities to improve retention.

The title sounds plausible, but the description crosses several role families:

customer success;
operations;
business analysis;
support handoffs;
retention work;
process documentation.

A Role Intelligence Report would help the advisor review whether the client is describing a customer-facing success role, an internal operations role, a business analyst, a support operations lead, or a hybrid. It would also surface missing details, such as tools, metrics, seniority, decision authority, and whether the role owns customer outcomes or internal processes.

How HR Advisory Teams Can Use It

HR advisors, fractional HR teams, recruiting-service consultants, and workforce advisory teams can use this report to:

clarify client expectations before search or job-description finalization;
improve role-intake notes;
identify missing skill, tool, metric, or ownership evidence;
prepare better client clarification questions;
route ambiguous roles to consultant review;
compare a manual interpretation with structured occupation and skill evidence.

The useful first step is not enterprise deployment. It is one careful review of one anonymized role description.

How To Test It

Start with one anonymized client role description that feels unclear or cross-functional.

Then compare:

the current manual role-intake interpretation;
the AvelinLabs job-analysis output;
the report-style summary of role clarity, occupation alignment, skill evidence, ambiguity, confidence, uncertainty, and client questions.

For the current beta, start with the HR-services role-intake payload or the complete Customer Grounding workflow in the examples repository.

Boundaries

The Role Intelligence Report is decision-support for human review. It is not final truth.

It does not replace consultants, recruiters, ATS products, HRIS systems, LMS systems, payroll systems, or professional judgment. It does not provide candidate sourcing, candidate matching, automated hiring, a production SLA, or a proven ROI claim.

Examples are illustrative unless identified as captured responses. The report-format example does not imply a dedicated ungrounded report endpoint. The controlled-beta grounded report route is documented separately and requires an authorized Runtime API Key contract.