# Powershell master-route.ps1 Execution Flow and Parameters: Complete Technical Guide

> Explore the execution flow and parameters for PowerShell master-route.ps1. This guide details how the primary router script matches task hints to skills using regex and generates route-scope.md.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: complete-technical-guide
- Published: 2026-08-18

---

**`master-route.ps1` is the PRIMARY router script for the reverse-skill framework that matches task hints to appropriate skills via regex-based keyword scoring and generates a [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) file for downstream consumption.**

This PowerShell script serves as the central dispatcher in the **zhaoxuya520/reverse-skill** repository. It interprets natural language task descriptions, evaluates them against configurable routing rules, and produces a deterministic output that automation pipelines can consume. Whether you're integrating reverse engineering workflows or extending the framework with new skills, understanding this execution flow is essential.

## Parameters and Input Handling

The script accepts three optional parameters defined in the `param` block at lines 6-10 of `skills/scripts/master-route.ps1`:

| Parameter | Purpose | Default Behavior |
|-----------|---------|----------------|
| **`-Hint`** | Free-text task description (e.g., `"extract password hashes"`) | Empty string; converted to lowercase for matching |
| **`-OutDir`** | Destination folder for [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) | Auto-generated timestamped directory under `work/` |
| **`-ProjectRoot`** | Explicit project root path for output isolation | Auto-detected via `WorkRoot.ps1` |

The `-Hint` parameter is the primary driver. The script normalizes it to lowercase at line 14 (`$t = $Hint.ToLower()`) to ensure case-insensitive keyword matching against routing rules.

## Execution Flow: Step-by-Step

### 1. Load Routing Configuration

The script locates and parses [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) as its single source of truth (lines 20-28). This JSON file contains:

- Route definitions with `keywords` arrays
- `priority` ordering for tie-breaking
- `meta.fallbackId` for unmatched hints

If the configuration file is missing or malformed, the script terminates with **exit code 2** (lines 29-33).

### 2. Keyword Matching and Scoring

For each route definition, the script evaluates three regex-based conditions (lines 35-52):

- **`must`** — Required regex that must match for the rule to qualify
- **`mustAll`** — Array of regexes where all must match
- **`exclude`** — Disqualifying regex; if matched, the rule is discarded

Successful matches accumulate in `$sel`, with each hit incrementing a per-route score (lines 54-59). This "plus-one per match" scoring preserves historic behavior from earlier framework versions.

### 3. Priority Validation and PRIMARY Selection

Before selecting a winner, the script validates that the `priority` list and route definitions remain synchronized (lines 64-72). Divergence triggers a warning but does not halt execution.

The PRIMARY skill selection follows this logic (lines 74-87):

1. Iterate routes in `priority` order
2. Select the route with highest accumulated score
3. If no route scores, fall back to `meta.fallbackId`

### 4. Confidence Determination

The script assigns confidence levels based on match uniqueness (lines 90-97):

| Condition | Confidence Level |
|-----------|----------------|
| Single unique route matched | `high` |
| Multiple routes tie for top score | `medium` |
| Fallback route activated | `low` |

### 5. Project Root Resolution

At lines 105-112, the script imports `skills/scripts/lib/WorkRoot.ps1` and invokes `Resolve-ReverseProjectRoot`. This helper isolates router output from the skill package itself, ensuring clean separation of framework code from user project data.

### 6. Output Directory Preparation

If `-OutDir` is omitted, the script creates a timestamped folder (lines 113-118, 127-136):

```powershell

# Default pattern: <project_root>/work/master-route-YYYYMMDDHHMMSS/

```

Falls back to a system temporary directory if project resolution fails.

### 7. Skill Path Validation

Before generating output, the script verifies that the PRIMARY skill's script file exists (lines 119-126). Missing files trigger **exit code 2** with a descriptive error.

### 8. Generate [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md)

The final output is a UTF-8 with BOM markdown document (lines 139-169) containing:

- Original hint and normalized version
- PRIMARY skill ID, label, and confidence level
- Resolved project root path
- Secondary route candidates
- Processing notes and warnings

BOM encoding ensures Windows tooling compatibility.

## Usage Examples

### Basic Invocation

```powershell
.\master-route.ps1 -Hint "enumerate active processes"

```

Creates [`work/master-route-20230818-154200/route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/work/master-route-20230818-154200/route-scope.md) with the matched PRIMARY skill.

### Explicit Paths

```powershell
.\master-route.ps1 -Hint "dump browser cookies" `
                   -OutDir "C:\temp\my-route" `
                   -ProjectRoot "D:\my-reverse-project"

```

Directs output to `C:\temp\my-route` while resolving project context from `D:\my-reverse-project`.

### Embedded in Automation

```powershell

# Within a larger reverse engineering pipeline

$routeResult = & "$PSScriptRoot\master-route.ps1" `
    -Hint $taskDescription `
    -OutDir $stageOutput

$primarySkill = (Get-Content "$routeResult\route-scope.md" | 
    Select-String "^primary:\s*(.+)$").Matches.Groups[1].Value

```

## Key Dependencies and Related Files

| File Path | Role |
|-----------|------|
| `skills/scripts/master-route.ps1` | PRIMARY router implementation |
| [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) | Routing rules and priority configuration |
| `skills/scripts/lib/WorkRoot.ps1` | `Resolve-ReverseProjectRoot` function |
| [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) | Architectural documentation |
| `skills/<skill-id>/skill.ps1` | Actual skill scripts invoked post-routing |

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success — [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) generated |
| 2 | Configuration error — missing/invalid [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) or missing skill file |

## Summary

- **`master-route.ps1`** implements regex-based keyword scoring against [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) to select the appropriate skill for a task hint
- **Three parameters** control input (`-Hint`), output location (`-OutDir`), and project context (`-ProjectRoot`)
- **Confidence levels** (`high`/`medium`/`low`) indicate match certainty based on scoring distribution
- **Exit code 2** signals unrecoverable configuration or validation failures
- **UTF-8 BOM encoding** ensures Windows compatibility for the generated [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md)

## Frequently Asked Questions

### How does `master-route.ps1` handle ambiguous hints that match multiple routes?

When multiple routes achieve identical top scores, the script selects the first match in `priority` order and assigns `medium` confidence. This deterministic tie-breaking ensures reproducible behavior across invocations. The unselected high-scoring routes appear in the `secondary` section of [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) for operator review.

### What happens if the [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) file is corrupted or missing?

The script validates JSON parsing at lines 29-33. Malformed or absent configuration triggers immediate termination with **exit code 2**. No [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) is generated, and error details emit to the error stream. Always verify [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) exists before invocation in automated pipelines.

### Can I override the fallback route without modifying the routing configuration?

No — the fallback behavior is controlled exclusively by `meta.fallbackId` in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json). To change the default route for unmatched hints, edit that JSON value. The `-Hint`, `-OutDir`, and `-ProjectRoot` parameters do not influence fallback selection; they only affect input processing and output placement.

### Why does the script use UTF-8 with BOM instead of plain UTF-8?

PowerShell's default file encoding on Windows systems produces files that some external tools misinterpret without BOM. The explicit UTF-8 BOM at line 169 ensures predictable handling by editors, diff tools, and downstream automation that may process [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md). This prevents character encoding surprises in mixed-platform environments.