How Priority Ordering in `routing.json` Controls Route Selection in reverse-skill

The priority array in routing.json serves as a deterministic tie-breaker: when multiple routes match a request with equal scores, the first route appearing in the priority list wins, ensuring consistent and predictable routing decisions.

The routing.json file in the reverse-skill repository (zhaoxuya520/reverse-skill) is the single source of truth for all task-routing rules. When a user submits a request, the routing engine evaluates keyword patterns across 41+ defined routes (R1 through R41) to determine the best match. Understanding how the priority ordering influences this process is essential for maintaining reliable request handling.

How Route Selection Works

The routing engine follows a three-phase selection process defined in skills/config/routing.json:

1. Candidate gathering — collect every route whose keyword patterns match the incoming request
2. Score calculation — each matched keyword adds to its route's score according to the meta scoring rules
3. Priority-based selection — iterate the priority array and select the first route with the maximum score

The priority array (lines 16-21 of routing.json) is the critical final step. The engine loops through this ordered list and picks the first route that achieved the highest match score. If no keywords match at all, the system falls back to fallbackId (R0).

The Role of Priority Ordering

Tie-Breaking for Equal Scores

When two or more routes achieve identical match scores, the priority array eliminates ambiguity. The route appearing earlier in the array wins automatically. This design guarantees that the same request always resolves to the same primary route, regardless of hash ordering or runtime conditions.

Deterministic Selection

As implemented in skills/scripts/master-route.ps1, the selection logic explicitly iterates $cfg.priority (lines 74-79):

# Load routing configuration

$cfg = Get-Content $ConfigFile -Raw | ConvertFrom-Json

# Build candidate set with scores …

foreach ($routeId in $cfg.routes.Keys) { … }

# Iterate priority list to pick primary route

$priority = @($cfg.priority)
foreach ($p in $priority) {
    if ($candidates.ContainsKey($p) -and $candidates[$p].Score -eq $maxScore) {
        $primary = $p
        break
    }
}

The break statement on match ensures only the highest-priority winner is selected.

Priority as a Consistency Guard

The priority array doubles as a validation target for repository integrity. The verify-routing-coherence.ps1 script enforces a strict one-to-one mapping between defined routes and priority entries.

Validation Logic

Lines 66-71 in verify-routing-coherence.ps1 perform this check:

$missingPrio = @($routeIds | Where-Object { $_ -notin @($rj.priority) })
$extraPrio   = @($rj.priority | Where-Object { $_ -notin $routeIds })
if ($missingPrio.Count -eq 0 -and $extraPrio.Count -eq 0) {
    Write-Host 'routing.json priority covers all routes (1:1)'
}

Any mismatch triggers a warning:

• Missing priority entry: a route exists but isn't ranked
• Extra priority entry: a ranked route doesn't exist

This prevents silent routing errors when developers add new routes without updating the priority table.

Key Files and Their Responsibilities

File	Purpose
skills/config/routing.json	Defines routes, keyword patterns, scoring rules, and the priority array
skills/scripts/master-route.ps1	Runtime router applying priority ordering to select the primary route
skills/scripts/verify-routing-coherence.ps1	Validates 1:1 mapping between route IDs and priority entries
skills/MASTER-ROUTING.md	Human-readable documentation that must stay synchronized with routing.json

Summary

• Tie-breaker: The priority array resolves equal-score conflicts by preferring earlier entries
• Deterministic routing: Same inputs always produce identical route selections
• Integrity enforcement: Validation scripts ensure every route has a priority rank and vice versa
• Fallback protection: Unmatched requests route to R0 via fallbackId

Frequently Asked Questions

What happens if two routes have the same match score?

The route appearing earlier in the priority array wins. The selection loop in master-route.ps1 iterates priority order and stops at the first candidate with the maximum score, making position in the array the decisive factor.

Why is the priority array validated separately from route definitions?

The verify-routing-coherence.ps1 script enforces this to prevent silent misconfigurations. A new route without a priority entry would never be selected; a priority entry without a route would cause lookup failures. The 1:1 validation catches both cases before deployment.

Can I change priority ordering without modifying route definitions?

Yes. The priority array is independent of the routes object in routing.json. You can reorder priorities to adjust tie-breaking behavior without touching keyword patterns or scores. However, you must synchronize MASTER-ROUTING.md to maintain documentation accuracy.

What occurs when no route keywords match?

The routing engine falls back to the route specified by fallbackId (R0). This default route handles unmatched requests, ensuring the system always produces a routing decision even with zero keyword overlap.

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