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

The Single Source of Truth (SSoT) for reverse-skill's execution chain is the 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 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. 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, the execution hot-path is strictly defined as: run the native platform router → resolve PRIMARY directive from 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 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)

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: The Linux, macOS, and Kali router that accepts a --hint parameter and implements identical matching logic

Both scripts read 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:

# 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, 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 with the --hint flag:

# Example: Find the skill for binary disassembly

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

Both commands ultimately read the same 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:

{
  "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 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:

# 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 and 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 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 is the immutable, authoritative source for all reverse-skill routing decisions
• Platform Consistency: Both master-route.ps1 and 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 must follow the JSON source; 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 always takes precedence over advisory documentation. According to 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 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 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 to point to a different configuration violates the SSoT principle established in RULES.md. The repository architecture assumes all tooling consumes 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, 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.

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