# Understanding the Role-Map: How Roles Are Assigned to Skills in reverse-skill

> Discover the role-map in reverse-skill. Learn how roles like lead and specialist are assigned to skills via the master routing engine for efficient security workflows.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: deep-dive
- Published: 2026-08-08

---

**The role-map in the reverse-skill repository is a structured configuration file ([`skills/ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/role-map.md)) that defines operational roles like `lead`, `specialist`, `cre`, `cie`, and `cpe`, and assigns them to specific skills through the master routing engine to ensure correct agent engagement during security workflows.**

The `zhaoxuya520/reverse-skill` project implements a rigorous role-based access system for security investigations. At the center of this system lies the **role-map**, a dedicated configuration that determines which operator or agent executes each stage of a skill workflow. This article examines the structure of [`skills/ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/role-map.md) and explains how the routing engine assigns these roles to skills during case execution.

## What Is the Role-Map in reverse-skill?

The role-map serves as the authoritative source for operational role definitions within the repository. Located at [`skills/ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/role-map.md), this file establishes a fixed set of responsibility tiers—including `lead`, `specialist`, `cre` (Customer Reliability Engineering), `cie` (Customer Incident Engineering), and `cpe` (Customer Platform Engineering)—and maps each role to concrete skills that operators must execute at specific workflow stages.

Rather than allowing arbitrary role assignment, the reverse-skill framework requires that every phase of a security investigation explicitly reference this mapping. This ensures that only designated experts perform critical actions, creating an auditable chain of custody for forensic activities.

## Core Components of the Role-Map Structure

The role-map defines three critical fields that govern how skills are delegated:

### lead_role

The `lead_role` field identifies the **primary executor** for the current investigation phase. According to the source code in [`skills/ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/role-map.md), the routing logic explicitly designates the main skill and sets `lead_role=lead` when initiating a workflow phase. This assignment establishes who holds primary responsibility for the investigation's current stage.

### specialist_roles

The `specialist_roles[]` array specifies **optional additional experts** required for complex phases. The role-map documentation describes how to "指定 specialist_roles[] 与 handoff 条件" (specify specialist_roles[] and handoff conditions), allowing the system to bring in domain-specific expertise—such as `cie` or `cpe`—when the primary skill requires supplemental capabilities.

### handoff Rules

The `handoff` field contains **transition logic** that triggers role changes when specific conditions are met. When a specialist completes their assigned task, the handoff mechanism ensures the workflow returns to the lead or transitions to the next appropriate role, maintaining continuity without manual intervention.

## How Roles Are Assigned to Skills

Role assignment occurs through an integrated routing system that consults the role-map at multiple execution points:

### Master Routing Integration

The **master routing engine** ([`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md)) pulls lead and specialist definitions directly from the role-map when constructing primary skill requests. As implemented in the source, the routing system references the role-map definitions to set the `lead` and `specialist` parameters before dispatching any skill execution command.

### Scope Contract Persistence

Once roles are determined, the **scope contract** ([`skills/ops/scope-contract.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/scope-contract.md)) records the chosen `lead_role` for traceability. This documentation step ensures that every case file contains a permanent record of which role was responsible for each action, supporting post-incident reviews and compliance audits.

### Workflow Execution Checkpoints

Throughout the workflow lifecycle—including [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md), [`skills/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/SKILL.md), and the governing [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md)—the system references the role-map to verify the correct person or agent is engaged before any `ACT` operation is performed. This verification prevents unauthorized execution of sensitive forensic commands.

In practice, the workflow begins when `case-init.ps1` generates a [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) file. The operator then consults the role-map to determine which skill (primary or specialist) to launch, writes the selected roles into [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md), and proceeds with execution only after the role-map validation confirms proper assignment.

## Practical Implementation Examples

The following examples demonstrate how to assign roles using the reverse-skill framework:

```markdown

# Example: Assigning a lead role for a new phishing investigation

# 1️⃣  Identify the primary skill (e.g., `phishing-analysis`)

# 2️⃣  Open the role-map and set lead_role

lead_role = lead               # see role-map.md line 22

specialist_roles = [cie, cpe] # optional specialists (line 24)

# 3️⃣  Record in the case scope

#   work/<case>/scope.md

lead_role: lead
specialist_roles:
  - cie
  - cpe

```

```powershell

# PowerShell snippet used by the routing script

# Loads role-map values, injects them into the routing table

$roleMap = Get-Content -Path "$repoRoot/skills/ops/role-map.md"
$lead    = ($roleMap | Select-String 'lead_role').Line.Split('=')[1].Trim()
$spec    = ($roleMap | Select-String 'specialist_roles').Line -replace '.*\[(.*)\].*','$1' -split ',\s*'

# Build the routing request with the assigned roles

Invoke-MasterRoute -PrimarySkill $primary -Lead $lead -Specialists $spec

```

## Summary

- The **role-map** ([`skills/ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/role-map.md)) defines fixed operational roles including `lead`, `specialist`, `cre`, `cie`, and `cpe` for the reverse-skill framework.
- **Role assignment** occurs through the master routing engine, which consults the role-map to set `lead_role` and `specialist_roles[]` before executing any skill.
- The **scope contract** ([`skills/ops/scope-contract.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/scope-contract.md)) persists role selections for audit trails, while [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) enforces role-map verification before any `ACT` operation.
- **Handoff rules** within the role-map manage transitions between primary and specialist roles during multi-stage investigations.

## Frequently Asked Questions

### What file defines the role-map in the reverse-skill repository?

The role-map is defined in [`skills/ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/role-map.md). This file contains the canonical definitions for all operational roles and their associated skill assignments, serving as the single source of truth for the routing engine.

### How does the master routing system use the role-map?

According to [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md), the master routing system reads the `lead_role` and `specialist_roles[]` definitions from the role-map when building primary skill requests. This integration ensures that every routed skill includes the correct responsible parties before execution begins.

### What is the difference between lead_role and specialist_roles?

The `lead_role` designates the **primary executor** responsible for the current investigation phase, while `specialist_roles[]` specifies **optional domain experts** brought in for specific technical requirements. The lead maintains overall case ownership, whereas specialists contribute targeted expertise under handoff conditions defined in the role-map.

### Where is the assigned role recorded during a case?

Role assignments are recorded in the **scope contract** at [`skills/ops/scope-contract.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/scope-contract.md) and persisted in the case-specific [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) file generated by `case-init.ps1`. This documentation creates an auditable trail showing which role performed each action throughout the investigation lifecycle.