# How to Debug Routing Mismatches with master-route.ps1 in Reverse-Skill

> Debug routing mismatches in Reverse-Skill using master-route.ps1. Inspect routing.json and route-scope.md with verbose output to fix incorrect skill rule matches.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-13

---

**Use `master-route.ps1 -Verbose` combined with inspection of [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) and the generated [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) file to identify why your task hint is matching the wrong skill rule.**

`master-route.ps1` is the primary triage script in the **reverse-skill** repository that determines which skill should handle a given task based on keyword matching against [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json). When the script routes a hint to an unexpected skill—a **routing mismatch**—you need systematic debugging to trace where the decision logic diverged. This guide walks through the exact steps, common pitfalls, and diagnostic tools built into the reverse-skill project.

## Understanding the Routing Architecture

Before debugging, you need to know how `master-route.ps1` makes its decisions. The script follows a four-stage pipeline as implemented in `skills/scripts/master-route.ps1`:

1. **Load [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)** – the single source of truth containing all keyword rules (`must`, `mustAll`, `exclude`) that map hints to skill identifiers
2. **Parse and normalize the hint** – tokenizes the input string, converts to lowercase, and trims punctuation
3. **Select the best match** – evaluates rules in order; the first rule satisfying all required terms and none of the excluded terms wins
4. **Write diagnostic output** – generates `work/master-route-<timestamp>/route-scope.md` containing the matched rule, score, and raw token list

The script also invokes `skills/scripts/case-guard.ps1` to ensure the repository is in an authorized state before execution proceeds.

## Step-by-Step Debugging Workflow

### Step 1: Verify the Exact Hint String

Small differences in spelling, spacing, or punctuation change tokenization and break rule matches.

```powershell

# Echo the exact string you're passing

$hint = "Active Directory privilege escalation"
Write-Host "Hint tokens:" ($hint -split '\s+')

```

Tokenization splits on whitespace. `"web app"` becomes two tokens; a rule expecting `"webapp"` as a single token will never match.

### Step 2: Inspect the Rule Definition in routing.json

Open [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) and locate the rule you expect to match. Examine three critical arrays:

- **`must`** – at least one term must be present
- **`mustAll`** – every term must be present
- **`exclude`** – any term here vetoes the match entirely

Overly strict `exclude` lists are a frequent cause of unexpected vetoes.

### Step 3: Run with Verbose Output

The `-Verbose` switch exposes the internal decision tree:

```powershell
powershell -File skills/scripts/master-route.ps1 -Hint "Active Directory privilege escalation" -Verbose

```

This prints the token list, rule evaluation order, and which rule finally matched—showing exactly where logic diverged from your expectation.

### Step 4: Examine the Generated Scope File

Each run creates a timestamped directory with diagnostic output:

```powershell

# Find and display the most recent routing scope

Get-ChildItem -Path work/master-route-* -Filter route-scope.md | 
    Sort-Object LastWriteTime -Descending | 
    Select-Object -First 1 | 
    Get-Content

```

The scope file records: the original hint, chosen skill ID, matched rule ID, match score, and complete token list.

### Step 5: Run the Automated Test Suite

The project includes 162 routing test cases to catch regressions:

```powershell
powershell -File skills/scripts/test-routing.ps1

```

If your hint belongs to an existing case, the suite highlights the exact failure with expected vs. actual skill routing.

### Step 6: Verify Rule Coherence

Hidden conflicts between rules cause unpredictable matching order:

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

```

This script detects unreachable rules, duplicates, and logical conflicts in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) that can trigger unexpected matches.

### Step 7: Update the Rule and Re-Test

After identifying the issue, modify [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) and re-run:

```powershell

# Edit skills/config/routing.json

# Then verify with the same hint

powershell -File skills/scripts/master-route.ps1 -Hint "your task description" -Verbose

```

Changes take effect immediately—no rebuild required.

## Common Routing Mismatch Pitfalls

| Pitfall | Cause | Prevention |
|---------|-------|------------|
| **Whitespace sensitivity** | Tokenization splits on spaces; multi-word phrases need consistent handling | Verify token count with `$hint -split '\s+'` |
| **Case sensitivity in custom scripts** | Core script normalizes to lowercase, but helper scripts may inject uppercase literals | Audit all hint-generation code for case consistency |
| **Over-broad exclude lists** | Single unrelated term in `exclude` vetoes valid matches | Review `exclude` arrays for unnecessary entries |
| **Stale test results** | After editing [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json), cached results mislead | Always rerun `test-routing.ps1` after JSON changes |

## Complete Debugging Example

```powershell

# Basic usage — route a pentest task

powershell -File skills/scripts/master-route.ps1 -Hint "Active Directory privilege escalation"

# Debug mode — see why a different skill was chosen

powershell -File skills/scripts/master-route.ps1 -Hint "Active Directory privilege escalation" -Verbose

# Inspect the decision record

Get-ChildItem work/master-route-* | Sort LastWriteTime | Select -Last 1 | Get-ChildItem | Get-Content

# Validate the entire rule set

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

```

## Key Files Reference

| File | Purpose |
|------|---------|
| `skills/scripts/master-route.ps1` | Core routing engine with `-Verbose` diagnostic mode |
| [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) | Single source of truth for keyword-to-skill mapping |
| [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) | Human-readable specification of routing behavior |
| `skills/scripts/test-routing.ps1` | 162-case automated regression test suite |
| `skills/scripts/verify-routing-coherence.ps1` | Detects unreachable, duplicate, or conflicting rules |
| `skills/scripts/case-guard.ps1` | Authorization gate before routing execution |

## Summary

- **Start with `-Verbose`** to expose tokenization and rule evaluation order
- **Inspect [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)** directly—rule definitions are the only source of routing logic
- **Read [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md)** in the timestamped `work/master-route-*` directory for the official decision record
- **Run `test-routing.ps1`** to catch regressions across all 162 test cases
- **Execute `verify-routing-coherence.ps1`** to find hidden rule conflicts
- **Watch for whitespace, case, and `exclude` list issues** as the most common mismatch causes

## Frequently Asked Questions

### How does master-route.ps1 decide which skill to route to?

The script tokenizes and normalizes the `-Hint` string, then evaluates rules in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) sequentially. The first rule where all `must`/`mustAll` terms are present and no `exclude` terms are found becomes the match. The corresponding skill ID is designated as PRIMARY and written to [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md).

### Where does master-route.ps1 store its diagnostic output?

Each execution creates a directory at `work/master-route-<timestamp>/` containing [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md). This file records the input hint, selected skill, matched rule ID, match score, and complete token list. Use `Get-ChildItem` to find the most recent directory by `LastWriteTime`.

### What is the difference between must and mustAll in routing.json?

`must` requires **at least one** of the listed terms to be present in the hint. `mustAll` requires **every** listed term to be present. A rule can specify both—`must` for alternative keywords, `mustAll` for mandatory compound concepts. Either failing causes the rule to be skipped.

### Why does my hint match the wrong rule even with -Verbose showing correct tokens?

Rule evaluation order matters—[`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) is processed top-to-bottom. An earlier rule with looser `must` requirements may match before your intended rule is evaluated. Use `verify-routing-coherence.ps1` to detect ordering issues and consider adding `exclude` terms to the over-eager rule.