# Where Is the Single Source of Truth for Reverse-Skill Routing Rules?

> Discover the single source of truth for reverse-skill routing rules: routing.json. This file centrally manages all task routing decisions for PowerShell and Bash scripts.

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

---

**The single source of truth for reverse-skill routing rules is the [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) file, which serves as the authoritative configuration for all task routing decisions across PowerShell and Bash scripts.**

The **reverse-skill** framework centralizes its routing logic in a single JSON configuration to eliminate configuration drift. According to the zhaoxuya520/reverse-skill repository, this file is the definitive location where all routing priorities, keywords, and route definitions are maintained. All routing scripts and verification tools read exclusively from this location, ensuring consistent behavior across different execution environments.

## The Centralized Routing Configuration

The **[`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)** file is explicitly designated as the **single source of truth (SSOT)** for the entire routing system. The file's `meta` section contains a direct declaration in both Chinese and English stating that this configuration is the authoritative record:

> “reverse‑skill 任务路由的 **单一事实源 (Single Source of Truth)** … 修改路由规则请只改此文件，勿改散落在 markdown / ps1 里的路由表（文档由生成脚本维护，或至少与本站保持一致）.”

This means that any changes to routing logic—whether updating keyword patterns, adjusting priority orders, or adding new routes—must be made exclusively in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json). Other files in the repository, including markdown documentation and PowerShell scripts, contain generated or mirrored copies that must remain synchronized with this central configuration.

## How Routing Scripts Consume the Configuration

Both the PowerShell and Bash implementations of the router load their routing data directly from [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) at runtime. This ensures that regardless of the shell environment, the routing decisions are derived from the same authoritative source.

### PowerShell Implementation

In `skills/scripts/master-route.ps1`, the router loads the JSON configuration using standard PowerShell cmdlets and iterates through the route definitions to match input hints against keyword patterns:

```powershell

# master-route.ps1 loads the routing rules

$RoutingPath = Join-Path $PSScriptRoot '..\config\routing.json'
$Routing = Get-Content $RoutingPath -Raw | ConvertFrom-Json

# Find the route whose keywords match the hint

foreach ($routeId in $Routing.routes.Keys) {
    $route = $Routing.routes[$routeId]
    foreach ($kw in $route.keywords) {
        if ($Hint -match $kw.must) {
            $Primary = $routeId
            break
        }
    }
}

```

### Bash Implementation

The [`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh) script performs the same operation using `jq` for JSON parsing, demonstrating cross-platform consistency in how the framework accesses its routing rules:

```bash
#!/usr/bin/env bash
ROUTING_JSON="${BASH_SOURCE%/*}/../config/routing.json"
ROUTES=$(jq -r '.routes | keys[]' "$ROUTING_JSON")
for r in $ROUTES; do
    # extract keyword regexes for route $r and test against the hint

    if [[ "$HINT" =~ $(jq -r ".routes[\"$r\"].keywords[].must" "$ROUTING_JSON") ]]; then
        PRIMARY=$r
        break
    fi
done

```

## Validating Routing Consistency

To prevent configuration drift, the repository includes dedicated verification scripts that ensure secondary representations remain synchronized with the single source of truth in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json).

### Coherence Verification

The `skills/scripts/verify-routing-coherence.ps1` script explicitly compares the priority order defined in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) against the generated documentation in [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md). This ensures that any manual edits to markdown files are flagged if they diverge from the authoritative JSON configuration:

```powershell

# verify-routing-coherence.ps1 checks that the priority order in routing.json

# matches the order in skills/MASTER-ROUTING.md

$Routing = Get-Content "$PSScriptRoot/../config/routing.json" -Raw |
           ConvertFrom-Json
$PriorityFromJson = $Routing.priority
$PriorityFromMd   = (Get-Content "$PSScriptRoot/../MASTER-ROUTING.md") -match '^\s*\*\s*`(\w+)`' |
                    ForEach-Object { $Matches[1] }
if ($PriorityFromJson -ne $PriorityFromMd) {
    Write-Error "Priority mismatch!"
}

```

### Test Harnesses

Additional validation is provided by `skills/scripts/test-routing.ps1` and [`skills/scripts/test-routing.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/test-routing.sh), which serve as test harnesses that validate routing behavior against the live configuration in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json). These scripts confirm that keyword matching and priority resolution behave as expected according to the central configuration.

## Summary

- **[`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)** is the definitive single source of truth for all reverse-skill routing rules and must be edited directly when modifying routing behavior.
- **`master-route.ps1`** and **[`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh)** read routing data exclusively from the JSON configuration to ensure cross-platform consistency.
- **`verify-routing-coherence.ps1`** validates that generated documentation and other derived files remain synchronized with the central routing configuration.
- The `meta` section in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) explicitly designates the file as the authoritative source, warning against editing scattered routing tables in markdown or PowerShell files.

## Frequently Asked Questions

### What file contains the reverse-skill routing rules?

The **reverse-skill routing rules** are stored in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json). This JSON file is the single source of truth that defines all route priorities, keyword matching patterns, and route identifiers used by the framework.

### How do I modify routing rules in reverse-skill?

You must edit **[`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)** directly. The file's metadata explicitly warns against modifying routing tables scattered in markdown files or PowerShell scripts, as those are either generated or mirrored copies that must stay synchronized with the central JSON configuration.

### Which scripts read from the routing configuration?

The primary consumers are `skills/scripts/master-route.ps1` (PowerShell) and [`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh) (Bash), both of which load [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) at runtime to determine task routing. Additionally, `skills/scripts/verify-routing-coherence.ps1` reads the file to validate documentation consistency, while `test-routing.ps1` and [`test-routing.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/test-routing.sh) use it for behavioral testing.

### How does reverse-skill ensure routing consistency?

The framework employs `verify-routing-coherence.ps1` to detect drift between the authoritative [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) and derived documentation files like [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md). This verification script compares priority orders and flags mismatches, ensuring that the single source of truth remains accurate across the entire codebase.