# How Ambiguous Routing Scenarios Are Resolved Using the Full routing.md Matrix in the reverse-skill Platform

> Discover how the reverse-skill platform resolves ambiguous routing scenarios. Learn how the full routing.md matrix ensures accurate path selection and efficient communication.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: deep-dive
- Published: 2026-08-19

---

**The reverse-skill platform resolves ambiguous routing by falling back to a generic route (`R0`) and emitting a note that triggers consultation of the full disambiguation matrix in [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md).**

When an incoming task lacks clear keyword matches, the system's three-axis routing matrix—defined by **target type**, **user intent**, and **toolchain**—cannot confidently select a primary skill. This article explains the exact fallback mechanism, how the [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md) matrix handles disambiguation, and the specific PowerShell implementation that drives this process.

## What Triggers Ambiguous Routing in reverse-skill

Ambiguous routing occurs when the `master-route.ps1` script evaluates a user hint and finds **no strong keyword hits** across any defined route. In [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json), each route specifies `keywords` arrays with `must` and `should` conditions. When these conditions fail to accumulate points for any route, the system cannot proceed with normal priority-based resolution.

Common triggers include:

- **Mixed terminology** – Phrases like "unlock X / remove check" blend target type and intent in ways that no single route's keyword set captures strongly.
- **Cross-module tasks** – Workflows spanning multiple domains (e.g., APK → native → Frida) don't align with single-route definitions.
- **Novel or rare requests** – Tasks not yet covered by existing keyword patterns.

## The Six-Step Fallback Mechanism

The routing logic in `skills/scripts/master-route.ps1` processes every hint through a precise pipeline. When ambiguity arises, steps 1–4 execute normally, but step 5 activates the fallback path.

### Step 1: Load Configuration

```powershell

# master-route.ps1 lines 22-30

$config = Get-Content "skills/config/routing.json" | ConvertFrom-Json
$routes = $config.routes
$priority = $config.priority

```

The script reads [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) as the **single source of truth** for all route definitions and priority ordering.

### Step 2: Keyword Matching

```powershell

# master-route.ps1 lines 35-52 (conceptual)

$hintLower = $Hint.ToLower()
$candidates = @{}

foreach ($routeId in $routes.PSObject.Properties.Name) {
    $route = $routes.$routeId
    $score = 0
    
    foreach ($kw in route.keywords) {
        if ($hintLower -match $kw.must) { $score += 2 }
        if ($kw.should -and ($hintLower -match $kw.should)) { $score += 1 }
    }
    
    if ($score -gt 0) { $candidates[$routeId] = $score }
}

```

Each route's keywords are evaluated against the lower-cased hint, with `must` matches weighted higher than `should` matches.

### Step 3: Scoring Accumulation

Candidate routes accumulate points based on keyword hits. The route with the highest score proceeds as the primary selection.

### Step 4: Priority Resolution

```powershell

# master-route.ps1 lines 74-87

if ($candidates.Count -gt 0) {
    $maxScore = ($candidates.Values | Measure-Object -Maximum).Maximum
    $topRoutes = $candidates.GetEnumerator() | 
                 Where-Object { $_.Value -eq $maxScore } |
                 Select-Object -ExpandProperty Key
    
    # Tie-break using priority array order

    foreach ($p in $priority) {
        if ($topRoutes -contains $p) { $primary = $p; break }
    }
}

```

When scores tie, the `priority` array in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) determines the winner—lower index wins.

### Step 5: Fallback Route Activation

```powershell

# master-route.ps1 lines 89-95

if ($null -eq $primary) {
    $primary = $config.fallbackId  # "R0"

    $note = "No strong keyword hit; open routing.md full matrix"
    $confidence = "low"
}

```

When `$primary` remains `$null` (no candidate achieved any score), the script selects `fallbackId` (`R0`) and attaches the critical note. This is the **decision point** that triggers full matrix consultation.

### Step 6: Ambiguous Intent Recovery Protocol

The note in step 5 triggers the protocol defined in [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md) lines 60–70. According to the reverse-skill source code, this protocol instructs the AI to:

1. **Restate the most likely technical objective** based on partial keyword matches.
2. **Favor the local-sandbox interpretation** when multiple valid readings exist.
3. **Present a short-step menu** allowing the user to confirm or redirect.

## How the routing.md Matrix Structures Disambiguation

The full matrix in [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) organizes routes across three dimensions, enabling systematic resolution of ambiguous cases:

| Dimension | Purpose | Example Values |
|-----------|---------|--------------|
| **Target Type** | What is being analyzed | APK, ELF, Mach-O, JavaScript, Firmware |
| **User Intent** | What operation is desired | Analyze, Patch, Unpack, Monitor, Fuzz |
| **Toolchain** | Preferred tooling approach | Frida, GDB, Ghidra, Custom scripts |

When the fallback note appears, downstream automation or users consult this matrix to locate the intersection matching their actual need. The matrix also documents **path-crossing examples**—common sequences where multiple routes could apply—and provides decision criteria for selecting between them.

## Practical Examples

### Invoking the Router with an Ambiguous Hint

```powershell

# Execute from repository root

powershell -NoProfile -ExecutionPolicy Bypass `
  -File skills/scripts/master-route.ps1 `
  -Hint "unlock X / remove check"

```

**Typical output:**

```

NOTE: No strong keyword hit; open routing.md full matrix
PRIMARY -> skills/reverse-engineering/SKILL.md
Label: General reverse-engineering | confidence: low

```

The router has selected `R0` (generic reverse-engineering) and explicitly signaled that manual disambiguation via the full matrix is required.

### Programmatic Handling of Ambiguity

```powershell

# Post-routing automation in downstream scripts

$routeScope = Get-Content "$OutDir/route-scope.md" -Raw

if ($routeScope -match 'No strong keyword hit') {
    # Load disambiguation matrix

    $matrix = Get-Content 'skills/routing.md' -Raw
    
    # Extract Recovery Protocol section

    $protocolSection = $matrix -split '## Ambiguous Intent Recovery Protocol' | 

                       Select-Object -Last 1
    
    # Parse protocol instructions for automated guidance

    $steps = $protocolSection -split "`r?`n" | 
             Where-Object { $_ -match '^\d+\.' }
    
    Write-Host "Ambiguity detected. Recovery steps:"
    $steps | ForEach-Object { Write-Host "  $_" }
}

```

This pattern allows CI/CD pipelines or IDE integrations to gracefully handle ambiguous inputs without manual intervention.

### Adding a New Route to Reduce Future Ambiguity

To prevent similar ambiguities, extend the routing configuration:

**1. Update [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json):**

```json
{
  "routes": {
    "R42": {
      "label": "License bypass analysis",
      "skill": "license-analysis/SKILL.md",
      "keywords": [
        { "must": "unlock|remove check|bypass license" }
      ]
    }
  },
  "priority": ["R1", "R2", ..., "R41", "R42"],
  "fallbackId": "R0"
}

```

**2. Add corresponding documentation in [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md)** under the appropriate target type and intent sections.

**3. Verify routing** with test hints:

```powershell
powershell -File skills/scripts/master-route.ps1 `
  -Hint "remove check from APK"

# Should now select R42 with high confidence

```

## Key Files in the Routing System

| File | Purpose | Critical Lines |
|------|---------|--------------|
| [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) | Central route definitions, keywords, priority order | Entire file—single source of truth |
| `skills/scripts/master-route.ps1` | Routing algorithm implementation, fallback logic, note generation | 22–30 (load), 35–52 (matching), 54–60 (scoring), 74–87 (priority), 89–95 (fallback) |
| [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) | Human-readable matrix, Ambiguous Intent Recovery Protocol | 60–70 (recovery protocol) |
| [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) | Post-routing execution guidelines, required downstream steps | 71–75 (follow-up actions) |

## Summary

- **Ambiguous routing** occurs when no route's keywords achieve a positive score in `master-route.ps1`.
- The **fallback mechanism** automatically selects route `R0` and emits a note directing users to the full matrix.
- The **three-axis matrix** in [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md) (target type × user intent × toolchain) provides structured disambiguation.
- The **Ambiguous Intent Recovery Protocol** restates objectives, favors local-sandbox interpretations, and presents decision menus.
- **Extending [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json)** with new keywords and routes prevents recurrence of specific ambiguity patterns.

## Frequently Asked Questions

### What happens if multiple routes have the same keyword score?

The `priority` array in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) resolves ties. `master-route.ps1` iterates through this array and selects the first route that appears in the tied candidate set. This ensures deterministic behavior even when keyword overlap creates scoring equivalence.

### Can the fallback route be customized or disabled?

The `fallbackId` in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) is configurable, but disabling it is not recommended. The system requires a valid fallback to handle novel inputs gracefully. To customize, modify `"fallbackId": "R0"` to reference any defined route—but ensure that route's [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) provides adequate generic guidance.

### How does the routing.md matrix differ from routing.json?

[`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) is machine-readable configuration consumed by `master-route.ps1`. [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md) is human-readable documentation with narrative explanations, path-crossing examples, and the Ambiguous Intent Recovery Protocol. The matrix supplements automated routing with contextual judgment that keyword rules cannot encode.

### What tools consume the "No strong keyword hit" note?

The note appears in [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) output and is designed for: (1) **IDE plugins** that can open [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md) automatically; (2) **CI pipelines** that may pause for manual input; and (3) **AI assistants** that parse the note to trigger the Recovery Protocol and guide interactive clarification.