# master-route.ps1 vs routing.md: Understanding the Primary Router and Advisory Matrix in zhaoxuya520/reverse-skill

> Learn the difference between master-route.ps1, the executable routing engine, and routing.md, the advisory matrix, in the zhaoxuya520/reverse-skill repository. Understand how skills are selected.

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

---

**The `master-route.ps1` script is the executable routing engine that programmatically selects skills, while [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) is a human-readable advisory matrix used only for documentation and manual disambiguation.**

In the `zhaoxuya520/reverse-skill` repository, routing decisions follow a clear separation of concerns: one automated, one advisory. The PowerShell script `master-route.ps1` at `skills/scripts/master-route.ps1` serves as the **single source of execution**, consuming [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) to match user hints against keywords, score candidates, and output a definitive [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md). The Markdown file [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) provides a **3-axis reference view** (Target Type × User Intent × Toolchain) that analysts consult when automated results need human verification.

---

## How master-route.ps1 Executes Primary Routing

The `master-route.ps1` script implements the complete routing logic through a four-stage workflow. It never hard-codes routes—every decision flows from the JSON configuration.

### Stage 1: Load the Configuration

The script reads [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) as its single source of truth. This JSON defines all available routes, their associated keywords, priority ordering, and fallback assignments.

### Stage 2: Match and Score Candidates

User hints are matched against the `keywords` array for each route. The script builds a candidate list, applies **priority-based scoring**, and ranks potential matches.

### Stage 3: Select PRIMARY or Fallback

The highest-scoring candidate becomes the **PRIMARY** skill. If no match exceeds the confidence threshold, the script falls back to the `fallbackId` defined in configuration.

### Stage 4: Generate route-scope.md

Output is written to [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) containing:
- Selected primary skill path
- Confidence level
- Secondary candidates
- Next-step instructions

The script exits with status `0` on success or `2` on configuration errors.

```powershell

# Execute the primary router with a user hint

.\skills\scripts\master-route.ps1 -Hint "decompile / IDA analyze"

```

---

## The Role of skills/routing.md as Advisory Matrix

Unlike the executable script, [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) performs **no programmatic routing**. Its purpose is documentation and human guidance through a structured 3-axis view.

### What the Matrix Contains

| Axis | Purpose |
|------|---------|
| Target Type | What is being analyzed (APK, ELF, PE, firmware, etc.) |
| User Intent | What the analyst wants to accomplish (decompile, debug, unpack, etc.) |
| Toolchain | Recommended tools and skill modules for the combination |

### When to Consult routing.md

- The primary router's output shows **low confidence**
- Multiple candidate skills score similarly
- A reviewer needs to **verify mapping correctness**
- Training new team members on skill organization

### The Hierarchy Rule

The matrix explicitly acknowledges its subordinate role: **"JSON-driven script wins if sources disagree"**【2†L3-L5】. This prevents conflicting guidance—when automation and documentation diverge, the executable router's decision stands.

```powershell

# Open advisory matrix for human review

code .\skills\routing.md

```

Sample matrix entry:

| Target Type | Recommended Entry | Alternative |
|-------------|-------------------|-------------|
| APK / Android app | `apk-reverse/` — jadx decompile + apktool unpack | `ida-reverse/` if core logic is in `.so` |

---

## Key Architectural Differences

| Aspect | master-route.ps1 | skills/routing.md |
|--------|------------------|-------------------|
| **Function** | Executable routing engine | Documentation and guidance |
| **Input** | [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json), user hint | None (static reference) |
| **Output** | [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) with PRIMARY skill | None (human reads directly) |
| **Automation** | Fully automated | Manual consultation only |
| **Source of truth** | Secondary (reads JSON) | None (advisory only) |
| **Update mechanism** | Modify [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) or script | Direct Markdown edits |
| **Exit codes** | `0` success, `2` config error | N/A |

---

## File Relationships and Dependencies

Three files form the complete routing system in `zhaoxuya520/reverse-skill`:

- **`skills/scripts/master-route.ps1`** — The routing engine【1†L3-L86】
- **[`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)** — Single source of truth for all route definitions
- **[`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md)** — Human-readable advisory matrix

The script consumes the JSON; the Markdown stands independent. Changes to routing **behavior** require JSON or script modifications. Changes to routing **documentation** require Markdown edits.

---

## Summary

- **`master-route.ps1`** is the **executable primary router** that reads [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json), scores candidate skills by keyword matching and priority, and outputs [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md)
- **[`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md)** is the **advisory matrix** providing 3-axis human guidance with no programmatic function
- The JSON-driven script **always prevails** when documentation and automation conflict
- Exit code `2` indicates configuration errors in the primary router
- Both systems serve distinct audiences: automation for speed, documentation for clarity and training

---

## Frequently Asked Questions

### What happens if routing.json and routing.md recommend different skills?

The `master-route.ps1` script's recommendation **always takes precedence**. The advisory matrix explicitly states that the JSON-driven script wins in conflicts【2†L3-L5】. The Markdown exists for human review, not override.

### Can I run the router without PowerShell?

No—`master-route.ps1` is a PowerShell script with no alternative implementation in the repository. The routing logic depends on PowerShell's JSON parsing, string matching, and file output capabilities.

### How do I add a new skill to the routing system?

Modify [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) to define the new route, its `keywords`, `priority`, and `fallbackId`. The script will automatically include it in candidate scoring. Optionally update [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) to document the new skill's placement in the 3-axis matrix.

### Why does the script generate route-scope.md instead of returning the skill directly?

The [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) file serves as an **audit trail** and **execution contract**. It captures not just the selected skill but confidence levels, secondary candidates, and next-step instructions—information that ephemeral console output would lose.