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

Use master-route.ps1 -Verbose combined with inspection of skills/config/routing.json and the generated 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. 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 – 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.

# 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 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 -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:

# 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 -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 -File skills/scripts/verify-routing-coherence.ps1

This script detects unreachable rules, duplicates, and logical conflicts in routing.json that can trigger unexpected matches.

Step 7: Update the Rule and Re-Test

After identifying the issue, modify routing.json and re-run:

# 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, cached results mislead	Always rerun test-routing.ps1 after JSON changes

Complete Debugging Example

# 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	Single source of truth for keyword-to-skill mapping
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 directly—rule definitions are the only source of routing logic
• Read 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 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.

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

Each execution creates a directory at work/master-route-<timestamp>/ containing 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 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.

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