# Single Source of Truth (SSoT) for reverse-skill's Execution Chain: Understanding routing.json Authority

> Discover the Single Source of Truth for reverse-skill's execution chain. Learn how routing.json configures skill routing for task hints.

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

---

**The Single Source of Truth (SSoT) for reverse-skill's execution chain is the [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) file, which serves as the sole authoritative configuration that platform-native router scripts consume to determine the PRIMARY skill for any given task hint.**

The zhaoxuya520/reverse-skill repository implements a deterministic routing architecture where consistency across Windows, Linux, and macOS depends on a centralized configuration. Unlike advisory documentation that may drift, this open-source project treats [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) as immutable infrastructure, ensuring that benchmarks, case-init guardrails, and automation tools all derive routing decisions from the same JSON schema.

## What Is the Single Source of Truth in reverse-skill?

In the reverse-skill codebase, the **Single Source of Truth (SSoT)** refers exclusively to [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json). This file contains the definitive mapping of task hints to skill executions, structured as a priority-ordered array of routing rules. According to [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md), the execution hot-path is strictly defined as: run the native platform router → resolve PRIMARY directive from [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json). No other configuration source—including markdown documentation or environment variables—can override the routing decisions encoded in this JSON file.

## How the Routing Table Controls Execution

### Structure of routing.json

The [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) schema defines two top-level keys that drive the entire execution chain:

- **`priority`**: An ordered array of rule IDs (e.g., `["R0", "R1", "R2", ...]`) that determines evaluation sequence
- **`routes`**: An array of rule objects, each containing:
  - `id`: Unique rule identifier (R0 through R44)
  - `keywords`: Array of matching terms
  - `mustAll`: Boolean indicating whether all keywords must match (`true`) or any keyword (`false`)
  - `skill`: File path to the corresponding SKILL.md (e.g., [`skills/reverse-engineering/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/reverse-engineering/SKILL.md))

With 43 active rules spanning R0 to R44, the configuration supports complex boolean logic while maintaining a flat structure that both PowerShell and Bash parsers consume without external dependencies.

### Platform-Native Router Implementation

The execution chain relies on two entry-point scripts that both parse the same JSON source:

- **`skills/scripts/master-route.ps1`**: The Windows router that accepts a `-Hint` parameter and outputs the resolved PRIMARY skill ID
- **[`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh)**: The Linux, macOS, and Kali router that accepts a `--hint` parameter and implements identical matching logic

Both scripts read [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) directly, ensuring platform-agnostic consistency regardless of the host operating system.

## Working with the Execution Chain

### Invoking the Router on Windows

Use `master-route.ps1` with the `-Hint` parameter to query the SSoT:

```powershell

# Example: Find the skill for APK decompilation

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/master-route.ps1 -Hint "apk decompile"

```

The script parses [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json), performs keyword matching against the hint, and returns the selected PRIMARY skill identifier.

### Invoking the Router on Linux, macOS, or Kali

Use [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) with the `--hint` flag:

```bash

# Example: Find the skill for binary disassembly

bash skills/scripts/master-route.sh --hint "binary disassembly"

```

Both commands ultimately read the **same** [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) file, guaranteeing that Windows and Unix systems resolve identical hints to the same skill IDs.

### Inspecting the Routing Table Directly

You can examine the SSoT structure to understand how rules are evaluated:

```json
{
  "priority": ["R0", "R1", "R2", "..."],
  "routes": [
    {
      "id": "R0",
      "keywords": ["obfuscation", "stuck"],
      "mustAll": true,
      "skill": "skills/reverse-engineering/SKILL.md"
    },
    {
      "id": "R1",
      "keywords": ["apk", "android"],
      "mustAll": false,
      "skill": "skills/apk-reverse/SKILL.md"
    }
  ]
}

```

The actual [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) contains 43 rules (R0–R44) with varying keyword combinations and boolean strategies.

### Verifying Routing Changes

To confirm that modifications to the SSoT are immediately reflected:

```bash

# 1. Edit skills/config/routing.json to add a test rule (e.g., id "RTEST")

# 2. Execute the router with a hint matching your new rule:

bash skills/scripts/master-route.sh --hint "my-new-scenario"

# 3. Verify the output references the expected RTEST skill path

```

## Advisory Documentation vs. the SSoT

While [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) and [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) provide human-readable priority lists and three-axis views of the routing logic, the reverse-skill architecture explicitly designates these as **advisory mirrors only**. Any divergence between these markdown files and [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) is resolved in favor of the JSON configuration.

The `skills/scripts/verify-routing-coherence.ps1` CI script enforces this hierarchy by validating that advisory documentation remains synchronized with the SSoT. If inconsistencies are detected, the script fails the build, preventing documentation drift from affecting production routing behavior.

## Summary

- **SSoT Location**: [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) is the immutable, authoritative source for all reverse-skill routing decisions
- **Platform Consistency**: Both `master-route.ps1` and [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) consume the same JSON file, ensuring identical behavior across Windows, Linux, and macOS
- **Rule Architecture**: The routing table contains 43 prioritized rules (R0–R44) with keyword arrays and boolean `mustAll` operators
- **Documentation Hierarchy**: Advisory files like [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) must follow the JSON source; [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) always wins conflicts
- **Integrity Enforcement**: The `verify-routing-coherence.ps1` script validates SSoT compliance in CI pipelines

## Frequently Asked Questions

### What happens if routing.json and MASTER-ROUTING.md contradict each other?

In the reverse-skill repository, [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) always takes precedence over advisory documentation. According to [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md), the execution chain resolves any divergence in favor of the JSON SSoT, and the CI script `verify-routing-coherence.ps1` is designed to catch these mismatches before they reach production.

### How do I add a new routing rule to reverse-skill?

To add a new rule, edit [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) directly by appending a new object to the `routes` array with a unique ID (e.g., "R45"), your target `keywords`, a `mustAll` boolean, and the `skill` path. After updating the JSON, run either `master-route.ps1` or [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) with a hint matching your new keywords to verify the router correctly selects your PRIMARY skill.

### Can I modify the router scripts to use a different configuration file?

While technically possible, modifying `master-route.ps1` or [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) to point to a different configuration violates the SSoT principle established in [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md). The repository architecture assumes all tooling consumes [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json), and diverging from this path would break benchmark reproducibility and case-init guardrails that depend on consistent routing behavior.

### Does the routing system support regex or only keyword matching?

Based on the schema in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json), the current implementation uses discrete keyword arrays with boolean logic controlled by the `mustAll` flag. The router scripts perform keyword containment checks rather than regex evaluation, making the routing deterministic and easily auditable across both PowerShell and Bash implementations.