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

The reverse-skill router evaluates target type, user intent, and available toolchain through master-route.ps1 and routing.md—when the wrong skill is selected, inspect the 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 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.

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

Open the generated report:

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:

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:

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

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:

Get-Content skills/tool-index.md

This file is auto-generated by refresh-tool-index.ps1 (Windows) or refresh-tool-index.sh (Linux/macOS). After installing new tools, refresh the index:

# 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 file (e.g., 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 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:

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

.\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	Run refresh-tool-index
Routing correct, execution blocked	RULES.md guard triggered	Review scope contracts in 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	Complete three-axis routing matrix
skills/MASTER-ROUTING.md	Human-readable fast ladder documentation
skills/tool-index.md	Auto-detected local tool inventory
skills/SKILL.md	Master entry point and ACT contract
RULES.md	Global execution guards

Summary

• Generate 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 after installing new tools to prevent silent rejection
• Review SKILL.md preconditions and 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 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 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 enforce scope contracts, authentication, and evidence-chain requirements. Additionally, each skill's 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.

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