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

> Learn how priority ordering in routing.json controls route selection in reverse-skill. Ensure consistent routing by understanding this deterministic tie-breaker for equal score routes.

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

---

**The `priority` array in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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):

```powershell

# 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:

```powershell
$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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) | Human-readable documentation that must stay synchronized with [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json). You can reorder priorities to adjust tie-breaking behavior without touching keyword patterns or scores. However, you must synchronize [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.