How Reverse-Skill Resolves Routing Conflicts: Deterministic Priority-Based Routing Explained

Reverse-Skill resolves routing conflicts through a deterministic, layered process that combines keyword scoring with a strict priority hierarchy, ensuring every user hint maps to exactly one primary route while providing automated fallback mechanisms for unmatched inputs.

The zhaoxuya520/reverse-skill repository implements a sophisticated routing system designed to eliminate ambiguity when multiple skills could handle a single user hint. Unlike systems that rely on arbitrary selection or complex rule engines, reverse-skill employs a transparent, score-based algorithm with explicit priority ordering to guarantee deterministic conflict resolution.

Centralized Route Definitions in routing.json

All routing logic originates from skills/config/routing.json, which serves as the single source of truth for route definitions, keyword rules, and priority ordering. This JSON file defines each route's identifier, associated SKILL.md path, and the regex patterns used for matching hints. No script contains hard-coded routing tables; every route modification must pass through this centralized configuration, which the verification script enforces to prevent configuration drift.

Keyword Matching and Scoring Algorithm

The primary routing logic resides in skills/scripts/master-route.ps1, which processes incoming hints through a multi-stage matching and scoring system (lines 41-59).

Stage 1: Regex-Based Candidate Selection

The script lower-cases the input hint into variable $t and evaluates it against each route's keyword rules. For each route, it checks must, mustAll, and exclude regex patterns:

foreach ($route in $cfg.routes.PSObject.Properties) {
    $id = $route.Name
    foreach ($kw in $route.Value.keywords) {
        $hit = $false
        if ($kw.must -and $t -match $kw.must) { $hit = $true }
        if ($hit -and $kw.mustAll) {
            foreach ($m in $kw.mustAll) { if ($t -notmatch $m) { $hit = $false; break } }
        }
        if ($hit -and $kw.exclude -and $t -match $kw.exclude) { $hit = $false }
        if ($hit) { $sel.Add($id) }
    }
}

Successful matches add the route ID to the candidate list $sel.

Stage 2: Accumulating Match Scores

For every candidate in $sel, the script increments a score counter stored in the $scores hashtable (lines 55-59). Routes matching multiple keyword rules accumulate higher scores, creating a quantitative basis for resolving routing conflicts when multiple routes match the same hint.

Priority-Based Tie-Breaking Hierarchy

When multiple routes achieve positive scores, reverse-skill resolves conflicts using a strict priority array defined in routing.json (lines 75-76). The algorithm iterates through the priority list and selects the highest-scoring route that appears earliest in this sequence (lines 79-86):

$primary = $null; $maxScore = -1
foreach ($p in $cfg.priority) {
    if ($scores.Contains($p) -and $scores[$p] -gt $maxScore) {
        $maxScore = $scores[$p]; $primary = $p
    }
}

This approach guarantees that routing conflicts resolve deterministically: if two routes share identical scores, the one with higher positional priority wins. The system never randomly selects or arbitrarily breaks ties.

Fallback Mechanisms and Safety Guardrails

The routing system implements multiple layers of defensive programming to handle edge cases and configuration errors gracefully.

Unmatched Hint Fallback

When no routes score (the hint contains none of the defined keywords), the script falls back to meta.fallbackId (typically R0) defined in routing.json (lines 91-95). It emits a diagnostic note directing users to consult skills/routing.md for available route options rather than failing silently or throwing errors.

Stale Priority Protection

If the computed primary ID does not exist in the current route list—such as when a priority entry references a deleted route—the script logs a warning and reverts to the fallback ID (R0) instead of crashing (lines 99-103). This ensures the system remains operational even when configuration inconsistencies exist.

Automated Coherence Verification

The skills/scripts/verify-routing-coherence.ps1 script provides continuous validation of the routing configuration to prevent conflicts at deployment time. It checks for mismatches between route definitions and the priority list, warning about missing or extra IDs (lines 30-33, 54-60, 86-90):

$routeIds = @($rjRoutes | ForEach-Object { $_.Name })
$missingPrio = @($routeIds | Where-Object { $_ -notin $rj.priority })
$extraPrio   = @($rj.priority | Where-Object { $_ -notin $routeIds })
if ($missingPrio.Count -eq 0 -and $extraPrio.Count -eq 0) {
    Ok 'routing.json priority covers all routes (1:1)'
} else {
    Bad "routing.json priority mismatch: missing=$($missingPrio -join ',') extra=$($extraPrio -join ',')"
}

This verification script disallows hard-coded routing tables and ensures the priority array maintains a 1:1 relationship with defined routes, catching potential routing conflicts before they reach production.

Summary

• Single Source of Truth: All route definitions live exclusively in skills/config/routing.json, preventing fragmentation.
• Quantitative Scoring: The master-route.ps1 script calculates match scores based on regex keyword rules, providing objective metrics for route selection.
• Deterministic Resolution: The priority array guarantees that ties resolve predictably based on explicit ordering rather than arbitrary selection.
• Resilient Fallbacks: The system defaults to meta.fallbackId (R0) for unmatched hints and invalid configurations, ensuring continuous operation.
• Automated Validation: The coherence verification script validates routing consistency and prevents configuration errors that could introduce routing conflicts.

Frequently Asked Questions

What happens when two routes have identical keyword match scores in reverse-skill?

When multiple routes achieve identical scores, the system consults the priority array in routing.json and selects the route appearing earliest in the list. This deterministic approach eliminates random selection and ensures consistent behavior across identical inputs.

Where is the routing configuration stored in the reverse-skill repository?

All routing definitions, keyword rules, and priority orderings reside in skills/config/routing.json. The system enforces this as the single source of truth; no scripts contain hard-coded routing tables, and the verification script actively prevents such practices.

How does reverse-skill handle hints that don't match any defined routes?

When no routes score (zero keyword matches), the script falls back to meta.fallbackId (typically R0) as defined in routing.json. It also emits a note suggesting the user consult skills/routing.md for available options, ensuring graceful degradation rather than system failure.

What prevents configuration errors from causing routing conflicts?

The verify-routing-coherence.ps1 script automatically validates the routing configuration, checking for mismatches between defined routes and the priority list, detecting missing or extraneous IDs, and ensuring all routing changes flow through routing.json. This catches inconsistencies before they can cause runtime routing conflicts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}