# How to Debug Routing Mismatches When the Wrong Skill Is Selected for a Task

> Debug routing mismatches and fix skill selection errors in your routing.json config. Learn to identify and resolve issues with keywords, priorities, and must statements for accurate task routing.

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

---

**Routing mismatches happen when the scoring algorithm in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) assigns higher points to an unintended route due to overly broad keyword patterns, conflicting priority ordering, or missing `must` statements that trigger the fallback route.**

The `zhaoxuya520/reverse-skill` repository relies on a centralized routing system to map task descriptions to specific skill files. All entry points—including `master-route.ps1`, [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh), and the CI verification pipeline—read the same JSON configuration to compute match scores. When the router selects the wrong skill, you must inspect the underlying rule definitions and priority array to identify the scoring discrepancy.

## Common Causes of Routing Mismatches

The routing engine evaluates every request against the rules defined in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json). When the wrong route wins, the root cause typically falls into one of these four categories.

### Keyword Pattern Mismatches

The `"must"` regex patterns determine whether a route qualifies for selection. If your task description contains terms that are not captured by the intended route's keywords, that route scores zero and the router falls back to a lower-priority match or the default `R0` route.

### Exclusion Pattern Interference

Routes can define `"exclude"` patterns that subtract points or disqualify matches entirely. A common error occurs when exclusion regexes unintentionally match words present in your task hint, causing the intended route to filter itself out of contention.

### Priority Array Ordering

When two routes compute identical scores, the router breaks ties using the ordered `priority` array at the bottom of [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json). If the unintended route appears earlier in this array, it wins the tie even when both patterns technically match your request.

### Fallback Route Activation

Route `R0` serves as the fallback when no rule scores above the threshold. If every route lacks a qualifying `"must"` pattern for your specific task, the router silently defaults to `R0`, indicating that your routing rules need broader keyword coverage.

## Step-by-Step Debugging Workflow

Follow this systematic approach to isolate and fix routing errors in the reverse-skill repository.

### 1. Run the Router with Verbose Output

Execute the primary router with the verbose flag to see exactly how each route scores against your task description.

```powershell

# PowerShell entry point

.\skills\scripts\master-route.ps1 -Hint "apktool decompile myapp.apk" -Verbose

```

```bash

# Bash entry point

./skills/scripts/master-route.sh -h "apktool decompile myapp.apk" -v

```

The output reveals which patterns matched, the computed score for each route (such as `R1` for APK reverse), and the final selection. Compare the winning route against your expected skill file.

### 2. Validate the JSON Structure

Run the coherence verification script to ensure [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) contains valid syntax and that every declared route maps to an existing skill file.

```powershell
.\skills\scripts\verify-routing-coherence.ps1

```

This script detects structural errors—such as missing skill files or priority mismatches—that can cause the router to behave unexpectedly.

### 3. Execute the Regression Test Suite

The repository includes 162 routing regression tests that validate known task-to-skill mappings.

```bash
./skills/scripts/test-routing.sh

```

If your specific task hint is already covered by the test suite, this script pinpoints exactly which rule is selecting the wrong route. Failures indicate that recent changes to [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) introduced a regression.

### 4. Inspect the Offending Route Definition

Open [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) and locate the entry for the route that was incorrectly selected (or the one that should have been selected but was skipped).

- Verify that the `"must"` regexes contain terms actually present in your task description.
- Check `"exclude"` patterns to ensure they do not match words from your hint.
- If the route uses `"mustAll"` or `"mustAny"` semantics, confirm all required sub-patterns are satisfied.

### 5. Adjust Priority to Break Ties

When two legitimate routes score equally, the `priority` array determines the winner. In [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json), move the intended route ID before the competing route ID within the priority list, or refine the keyword patterns to create a decisive score differential.

### 6. Retest and Verify

After editing [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json), repeat steps 2 and 3. All regression tests must pass before you commit the change, ensuring that your fix resolves the specific mismatch without breaking existing routing logic.

## Practical Debugging Example

Consider a scenario where the request "apktool decompile myapp.apk" incorrectly routes to `R0` instead of `R1` (APK reverse).

First, run the verbose diagnosis:

```powershell
.\skills\scripts\master-route.ps1 -Hint "apktool decompile myapp.apk" -Verbose

```

If the output shows **Selected PRIMARY route: R0**, inspect the `R1` definition in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json). You may discover that the `must` regex does not explicitly include `apktool`:

```json
{
  "id": "R1",
  "skill": "apk-reverse/SKILL.md",
  "keywords": {
    "must": "\\bapk\\b|smali|jadx|..."
  }
}

```

Add `apktool` to the pattern:

```json
{
  "must": "\\bapk\\b|apktool|smali|jadx|..."
}

```

Run the verification scripts to confirm the fix:

```bash
./skills/scripts/verbose-routing-coherence.ps1
./skills/scripts/test-routing.sh

```

## Key Files in the Routing System

Understanding these source files is critical when you debug routing mismatches:

- **[`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)** – The central routing table that defines all routes, their keyword patterns (`must`, `exclude`, `mustAll`), and the `priority` array used for tie-breaking.
- **`skills/scripts/master-route.ps1`** – The PowerShell entry point that parses [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json), computes route scores, and returns the matching skill file path.
- **[`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh)** – The Bash equivalent that implements the same scoring algorithm for cross-platform compatibility.
- **`skills/scripts/verify-routing-coherence.ps1`** – A CI-style validator that checks JSON integrity, ensures every route ID has a corresponding skill file, and verifies that the priority array contains all defined routes.
- **[`skills/scripts/test-routing.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/test-routing.sh)** – Executes the full suite of 162 regression tests to catch routing regressions after configuration changes.

## Summary

- **Verbose logging** (`-Verbose` or `-v`) exposes the exact scores computed for each route, revealing why a specific skill was chosen.
- **Structural validation** via `verify-routing-coherence.ps1` catches JSON syntax errors and missing skill file references that break the router.
- **Keyword refinement** in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) fixes mismatches caused by overly strict `"must"` patterns or overly broad `"exclude"` patterns.
- **Priority ordering** in the `priority` array resolves ties when multiple routes legitimately match the task description.
- **Regression testing** with [`test-routing.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/test-routing.sh) ensures that fixes for specific routing mismatches do not introduce new errors elsewhere in the system.

## Frequently Asked Questions

### Why does my task always route to R0 instead of the intended skill?

Route `R0` is the fallback that activates when no route in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) achieves a positive score. Verify that your intended route's `"must"` regex actually matches terms present in your task description. If the regex is too specific or uses word boundaries (`\b`) that exclude your input, the router cannot score that route and defaults to `R0`.

### How does the router decide between two routes with identical scores?

When two routes compute the same score, the router consults the `priority` array in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json). The route whose ID appears **earlier** in this array wins the tie. To change this behavior, reorder the priority array or refine the keyword patterns of one route to create a higher score differential.

### What is the difference between `must`, `mustAll`, and `mustAny` in routing rules?

The `"must"` field typically accepts a regex pattern that awards points if any match is found. `"mustAll"` requires every sub-pattern to match simultaneously for the route to qualify, while `"mustAny"` grants partial credit if any one of several patterns matches. These semantics determine whether a route scores high enough to be considered or is filtered out entirely.

### How can I test routing changes without affecting the live system?

Use the [`test-routing.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/test-routing.sh) script to run the 162 regression tests against your modified [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json). This script operates on a copy of the configuration and validates routing decisions against known expected outputs, allowing you to verify fixes locally before committing changes to the repository.