# How to Debug Routing Mismatches When the Wrong Skill Is Selected in reverse-skill

> Debug reverse skill routing mismatches by inspecting route scope reports, verifying keyword patterns, and checking tool availability. Learn how to fix incorrect skill selection for your routing.

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

---

**The reverse-skill router evaluates target type, user intent, and available toolchain through `master-route.ps1` and [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md)—when the wrong skill is selected, inspect the [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) report, verify keyword patterns, and check tool availability to pinpoint the mismatch.**

The reverse-skill framework routes reverse-engineering and pentesting tasks to specialized skill modules based on multi-dimensional scoring. When the router sends your request to an unexpected skill, systematic debugging of the decision pipeline in `skills/scripts/master-route.ps1` and its supporting files will reveal the root cause. This guide walks through the exact diagnostic steps implemented in the zhaoxuya520/reverse-skill repository.

## Understanding the Routing Architecture

The routing system operates on two complementary mechanisms:

- **Primary fast ladder** — A PowerShell script at `skills/scripts/master-route.ps1` that parses user hints, scores candidate skills via regex matching, and outputs a structured decision report.
- **Full matrix** — A human-readable reference at [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) that enumerates all supported target/intent/toolchain combinations.

Both sources must align for predictable routing behavior.

## Step 1: Generate and Inspect the Route-Scope Report

Start by reproducing the routing decision with explicit logging. The `-OutDir` parameter creates a timestamped folder containing [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md).

```powershell
.\skills\scripts\master-route.ps1 -Hint "decode this APK and extract smali" -OutDir "tmp/debug-route"

```

Open the generated report:

```powershell
Get-Content tmp/debug-route/route-scope.md

```

**Key fields to examine:**

| Field | Meaning |
|-------|---------|
| `primary` | The selected skill code (e.g., `R1`, `R0`) |
| `primary_label` | Human-readable skill name |
| `confidence` | `high`, `medium`, or `low` |
| `secondary` | Alternative candidates considered |
| `notes` | Diagnostic messages including fallback triggers |

A `primary: R0` value indicates the **generic fallback** activated—no specific regex pattern achieved sufficient confidence.

## Step 2: Verify Keyword Pattern Matching

Routing decisions depend on regex blocks defined from **line 101 onward** in `master-route.ps1`. Search for patterns relevant to your request:

```powershell
Select-String -Path .\skills\scripts\master-route.ps1 -Pattern 'apk|smali|jadx|dex'

```

The script uses PowerShell `-match` operators with word boundaries. A typical Android pattern appears as:

```powershell
$scored += if ($hint -match '\bapk\b|smali|jadx|dex2jar') { @{ label='APK reverse'; code='R1'; hits=($matches.Count) } }

```

**Common pattern failures:**

- Missing terminology (e.g., `OLLVM` vs. `obfus`)
- Case-sensitivity issues (patterns are case-insensitive by default, but verify)
- Overly specific patterns that exclude valid variants

## Step 3: Audit the Priority Resolution List

When multiple patterns match, the **$priority array** (lines 164-165 in `master-route.ps1`) determines the winner. Examine this array:

```powershell
Select-String -Path .\skills\scripts\master-route.ps1 -Pattern '\$priority'

```

The first matching skill in this ordered list receives the `primary` designation, regardless of match count. Ensure your intended skill precedes competing entries.

## Step 4: Validate Tool Availability

The router assumes tool presence; missing tools may cause silent skill rejection downstream. Check the tool index:

```powershell
Get-Content skills/tool-index.md

```

This file is auto-generated by `refresh-tool-index.ps1` (Windows) or [`refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/refresh-tool-index.sh) (Linux/macOS). After installing new tools, refresh the index:

```powershell

# Windows

.\skills\scripts\refresh-tool-index.ps1

# Linux/macOS

bash skills/scripts/refresh-tool-index.sh

```

## Step 5: Review Skill-Specific Preconditions

Each skill directory contains a [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) file (e.g., [`skills/apk-reverse/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/apk-reverse/SKILL.md)) defining **ACT steps**—preconditions the router expects you to complete. Skipping these can create a "wrong skill" perception when the actual issue is incomplete setup.

## Step 6: Check Global Execution Rules

Post-routing guards in [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) may block a correctly routed skill. Scope contracts, authentication checks, and evidence-chain requirements can all intercept execution. Review this file when routing appears correct but execution fails.

## Step 7: Refine the Hint or Extend the Matrix

If existing patterns cannot express your use case, you have two resolution paths:

**Option A: Optimize the hint**

Add clearer, more specific keywords that match existing patterns:

```powershell

# Weak hint

.\skills\scripts\master-route.ps1 -Hint "analyze mobile app"

# Strong hint

.\skills\scripts\master-route.ps1 -Hint "decompile APK to smali using jadx"

```

**Option B: Extend the routing logic**

1. Add a new row to [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) documenting the target/intent/toolchain combination
2. Append a corresponding `-match` pattern in `master-route.ps1` (after line 101)
3. Update `$priority` if the new skill competes with existing entries

## Step 8: Verify the Fix

Re-run the router and confirm **high confidence** for the expected skill:

```powershell
.\skills\scripts\master-route.ps1 -Hint "your refined request" -OutDir "tmp/verify-fix"
Get-Content tmp/verify-fix/route-scope.md | Select-String "primary|confidence"

```

Expected output indicators:
- `primary` matches your target skill code
- `confidence: high`
- `secondary` shows appropriate alternatives or `(none)`

## Typical Pitfall Patterns

| Symptom | Root Cause | Resolution |
|---------|-----------|------------|
| `R0` fallback with note "No strong keyword hit" | No regex exceeded threshold | Expand pattern breadth or refine hint |
| Correct pattern matches but wrong skill wins | Priority list ordering | Reorder `$priority` array |
| Skill routes correctly but fails to execute | Missing tool in [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) | Run `refresh-tool-index` |
| Routing correct, execution blocked | [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) guard triggered | Review scope contracts in [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) |

## Key Source Files Reference

| File Path | Purpose |
|-----------|---------|
| `skills/scripts/master-route.ps1` | Core routing logic: regex scoring, priority resolution, report generation |
| [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) | Complete three-axis routing matrix |
| [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) | Human-readable fast ladder documentation |
| [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) | Auto-detected local tool inventory |
| [`skills/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/SKILL.md) | Master entry point and ACT contract |
| [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) | Global execution guards |

## Summary

- **Generate [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md)** via `master-route.ps1 -OutDir` to capture the routing decision
- **Inspect regex patterns** from line 101 in the script for missing or mismatched keywords
- **Verify `$priority` array** ordering (lines 164-165) when multiple skills match
- **Refresh [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md)** after installing new tools to prevent silent rejection
- **Review [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) preconditions** and [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) guards** for post-routing blocks
- **Refine hints or extend patterns** when the matrix lacks coverage for your use case

## Frequently Asked Questions

### Why does reverse-skill fall back to R0 even when my request seems specific?

The R0 fallback triggers when no regex pattern achieves the confidence threshold. Check [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) for the note "No strong keyword hit"—this indicates zero or insufficient matches. Compare your hint wording against the `-match` patterns starting at line 101 in `master-route.ps1`. Adding explicit tool names (e.g., `jadx`, `ida`, `frida`) or file formats (e.g., `ELF`, `Mach-O`, `DEX`) typically resolves this.

### How do I add support for a new reverse-engineering target?

Extend both the documentation and the code: add a row to [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) describing the target/intent/toolchain combination, then implement a corresponding regex block in `master-route.ps1` after line 101. Update the `$priority` array if this new skill competes with existing entries. Finally, run `refresh-tool-index` to ensure any required tools are detected.

### What causes a skill to route correctly but fail during execution?

Post-routing guards in [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) enforce scope contracts, authentication, and evidence-chain requirements. Additionally, each skill's [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) defines ACT preconditions that must be satisfied before proceeding. The router's job ends at selection—execution failures typically stem from incomplete setup or policy violations rather than routing errors.