# How the Core Routing Flow Is Structured in reverse‑skill

> Explore the reverse-skill routing system and its JSON-driven keyword-matching algorithm for mapping user hints to skill modules on PowerShell and Bash.

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

---

**The reverse‑skill routing system maps free‑form user hints to skill modules through a JSON‑driven keyword‑matching algorithm that runs identically on PowerShell and Bash.**

Understanding how routing decisions are made is essential for extending the reverse‑skill framework. The routing flow in `zhaoxuya520/reverse‑skill` is built around a **single source of truth**—the JSON configuration at [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)—that both platform entry points consume to resolve user intent into executable skill paths.

## The Routing Architecture

At its core, reverse‑skill implements a **platform‑neutral routing pipeline**. Rather than duplicating logic across operating systems, the project maintains parallel implementations in PowerShell (`skills/scripts/master-route.ps1`) and Bash ([`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh)) that execute identical algorithms against the same structured data.

This design ensures that a routing decision on Windows produces the same result as on Linux, macOS, or Kali.

## Step‑by‑Step Routing Flow

### Step 1: Hint Parsing and Normalization

The routing flow begins when the user invokes `master-route` with a free‑form text hint:

```bash

# Bash entry point

bash skills/scripts/master-route.sh --hint "analyse Android APK and bypass certificate pinning"

```

```powershell

# PowerShell entry point

powershell -File skills/scripts/master-route.ps1 -Hint "Find hidden services in a Kubernetes cluster"

```

Both scripts perform identical preprocessing:

1. Convert the hint to lowercase
2. Tokenize and scan against regular‑expression patterns defined in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json)
3. Accumulate match scores per route ID

### Step 2: Keyword Matching and Scoring

The matching engine evaluates every route defined in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json). Each route contains a `"keywords"` array of regex patterns. For every pattern that matches the hint, the corresponding route receives a score increment.

The algorithm prioritizes **specificity through accumulation**—routes with multiple matching keywords outrank those with single matches.

### Step 3: Priority‑Based Route Selection

After scoring completes, the resolver iterates through the `"priority"` array in order. The first route ID in this list with a non‑zero score becomes the **PRIMARY** selection. This tiered approach ensures:

- **Deterministic tie‑breaking**: Earlier entries in `"priority"` win when scores are equal
- **Controlled fallback**: When no keywords match, the system defaults to `"fallbackId": "R0"`

### Step 4: Output Generation and User Direction

The resolved route triggers two outputs:

- A timestamped `route‑scope.md` file in `work/master-route-{YYYYMMDD-HHMMSS}/` containing the route label, skill file path, confidence level, and operational notes
- Console output directing the user to open the selected [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) and execute the action required

## Visualization of the Routing Flow

```

┌─────────┐     ┌─────────────────┐     ┌─────────────────────┐
│  Hint   │────→│  master-route   │────→│   routing.json      │
└─────────┘     │ (PS1 / Bash)    │     │ (single source of   │
                │                 │     │  truth)             │
                │  • lower‑case   │     └─────────────────────┘
                │  • keyword scan │              │
                │  • regex match  │              ▼
                │                 │     ┌─────────────────────┐
                └─────────────────┘     │  keyword matching   │
                        │               │  → scoring engine   │
                        │               └─────────────────────┘
                        │                        │
                        └────────────────────────┘
                                     │
                                     ▼
                          ┌─────────────────┐
                          │  priority list  │
                          │  iteration      │
                          └─────────────────┘
                                   │
                                   ▼
                    ┌──────────────────────────┐
                    │  PRIMARY route resolved  │
                    │  (SKILL.md path)         │
                    └──────────────────────────┘
                                   │
                    ┌──────────────┴──────────────┐
                    ▼                             ▼
            ┌─────────────┐               ┌─────────────┐
            │ route-scope │               │   console   │
            │   .md file  │               │   output    │
            │  (artifact) │               │  (user dir) │
            └─────────────┘               └─────────────┘

```

## Verification and Coherence Checking

To prevent drift between the JSON configuration and human‑readable documentation, reverse‑skill includes a dedicated verification script:

```powershell
powershell -File skills/scripts/verify-routing-coherence.ps1

# → "ALL ROUTING COHERENCE CHECKS PASSED"

```

`verify-routing-coherence.ps1` validates that:

- Every route ID in `"routes"` appears in the `"priority"` list
- The priority list contains no orphaned entries
- The markdown matrix ([`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md)) remains synchronized with the JSON source

This verification step ensures the **routing integrity** of the framework before deployment or after configuration changes.

## Key Files in the Routing System

| File | Responsibility |
|------|---------------|
| [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) | Central configuration: route definitions, keywords, priority order, fallback ID |
| `skills/scripts/master-route.ps1` | Windows entry point implementing the full routing algorithm |
| [`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh) | Linux/macOS/Kali entry point with matching logic |
| `skills/scripts/verify-routing-coherence.ps1` | Integrity checker for JSON/priority alignment |
| [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) | Contract documentation and usage guidelines |
| [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) | Three‑axis disambiguation matrix for vague hints |

## Summary

- **Single source of truth**: All routing decisions derive from [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)
- **Platform parity**: PowerShell and Bash entry points execute identical algorithms
- **Scoring + priority**: Routes accumulate keyword matches; priority list breaks ties deterministically
- **Automated verification**: Coherence checking prevents configuration drift
- **Structured output**: Every routing decision produces both artifacts ([`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md)) and actionable console guidance

## Frequently Asked Questions

### What happens if multiple routes have the same keyword match score?

The routing system uses the `"priority"` array as a deterministic tie‑breaker. The first route ID in this ordered list with a matching score wins. This design guarantees predictable, reproducible routing decisions regardless of input order or platform.

### Can I extend routing.json with new routes without modifying the scripts?

Yes. The routing algorithm is data‑driven—adding new route objects to [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) and including their IDs in the `"priority"` array automatically extends functionality. Run `verify-routing-coherence.ps1` after modifications to validate structural integrity.

### How does reverse‑skill handle platform differences between PowerShell and Bash?

Both `master-route.ps1` and [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) implement the same four‑step algorithm: hint normalization, regex keyword matching, priority‑based selection, and artifact generation. They differ only in syntax—JSON parsing, string manipulation, and file operations—while producing identical routing decisions from identical inputs.

### What is the purpose of the routing.md matrix?

[`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) provides a **human‑readable three‑axis reference** for disambiguating vague hints. When keyword matching is inconclusive or users are uncertain about phrasing, this matrix offers categorical guidance organized by domain, technique, and target platform.