# Troubleshooting Unexpected PRIMARY Skill Returns in master-route.ps1

> Troubleshoot unexpected PRIMARY skill returns in master-route.ps1 by checking hint strings, regex patterns, and priority order in routing.json. Resolve routing mismatches effectively.

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

---

**When `master-route.ps1` selects an incorrect PRIMARY skill, verify that the hint string is properly formatted and lowercased, then inspect the `must`/`mustAll` regex patterns and priority order in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) to resolve routing mismatches.**

The `master-route.ps1` script acts as the PRIMARY router for the *reverse-skill* framework, parsing user hints to determine which skill directory (e.g., [`apk-reverse/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/apk-reverse/SKILL.md)) should execute and writing the selection to [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md). When the script returns an unexpected skill ID, systematic debugging of the input processing and routing configuration isolates whether the issue stems from keyword matching, priority conflicts, or file path resolution.

## Verify Hint Input Formatting

The router normalizes all input via `$t = $Hint.ToLowerInvariant()` at the start of execution. Because the matching logic evaluates the lowercased string, any leading whitespace, missing quotes, or special characters in the original hint can cause unexpected misses.

- **Check quoting**: Ensure the `-Hint` parameter is enclosed in double quotes when invoking from the command line.
- **Trim whitespace**: Verify no leading or trailing spaces exist in the hint string.
- **Test explicitly**: Run the script with a controlled hint to confirm behavior:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass `
    -File skills/scripts/master-route.ps1 `
    -Hint "apk reverse"

```

## Inspect Keyword Matching Logic

The script builds a candidate list (`$sel`) by evaluating each route's `must`, `mustAll`, and `exclude` regex fields against the normalized hint. If the hint fails to match the specific regex patterns defined for your expected route, the router will either select a different route or fall back to the default.

- **Validate regex compatibility**: Copy the `must` and `mustAll` patterns from [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) into an online regex tester or use PowerShell's `-match` operator to verify they capture your hint.
- **Check exclusion rules**: Ensure the hint does not inadvertently trigger an `exclude` pattern that would disqualify the intended route.
- **Review scoring**: The router assigns scores based on these matches; if no route scores positively, fallback logic engages.

## Audit Route Priority Order

When multiple routes achieve identical scores, `master-route.ps1` selects the route that appears first in the `priority` array defined in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json). A valid route may be skipped if a higher-priority route also matches the hint.

- **Inspect `$cfg.priority`**: Open [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) and confirm the order of IDs in the `priority` list.
- **Reorder if necessary**: Move your target route's ID earlier in the array to ensure it wins ties, or add more specific `mustAll` constraints to competing routes to differentiate them.

## Validate Fallback Configuration

If no routing rule generates a positive score, the script defaults to the ID specified in `meta.fallbackId` (commonly `"R0"`). An unexpected PRIMARY result often indicates that no rules matched, triggering this fallback.

- **Check `meta.fallbackId`**: Verify this value in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) points to your intended default route, or debug why the intended route failed to score.
- **Review the R0 route**: Ensure the fallback route definition exists and maps to a valid skill path.

## Confirm Skill File Existence

After selecting a primary ID, the script constructs the absolute path `$skillAbs` pointing to `skills/<skill>/SKILL.md`. If the target file does not exist, the script aborts with **exit code 2** and logs a "PRIMARY skill missing" error.

- **Verify physical paths**: Confirm that the directory specified in the route's `skill` field exists under the `skills/` folder.
- **Check case sensitivity**: While Windows is case-insensitive, the path construction logic may fail on Linux runners if the file system case does not match the JSON definition.

## Interpret Diagnostic Output

The router accumulates diagnostic messages in the `$notes` array during execution. These notes appear in yellow console output and indicate specific failure modes such as "no strong keyword hit" or "primary id not in routes".

- **Watch for yellow output**: After running the script, scan for NOTE messages that explain why a route was rejected.
- **Enable verbose logging**: Invoke the script with the `-Verbose` flag or temporarily insert `Write-Host` statements in a local copy of `master-route.ps1` to inspect intermediate variables like `$t`, `$sel`, `$scores`, and `$primary`.

## Run Automated Verification

The repository includes dedicated scripts to validate configuration integrity and routing behavior.

**Verify configuration coherence**:

```powershell
powershell -File skills/scripts/verify-routing-coherence.ps1

```

This script checks for malformed JSON, hard-coded routing tables, and schema violations that would cause `master-route.ps1` to abort.

**Execute the regression test suite**:

```powershell
powershell -File skills/scripts/test-routing.ps1

```

This comprehensive suite covers 162 distinct routing scenarios. Any failing test case pinpoints a specific rule or priority conflict requiring correction.

## Summary

- **Input normalization**: The script lowercases hints via `$Hint.ToLowerInvariant()`; whitespace and quoting errors cause mismatches.
- **Keyword logic**: Routes require matching `must` or `mustAll` regex patterns; review these in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) if the wrong route scores.
- **Priority ties**: Identical scores defer to the order of the `priority` array; reorder or refine regex specificity to control selection.
- **Fallback behavior**: No valid match results in the `meta.fallbackId` route (default `R0`).
- **File validation**: Missing skill files trigger exit code 2; verify `$skillAbs` targets exist.
- **Diagnostic tools**: Use `verify-routing-coherence.ps1` for JSON validation and `test-routing.ps1` for regression testing against 162 scenarios.

## Frequently Asked Questions

### Why does master-route.ps1 return the fallback route R0 instead of my target skill?

This occurs when the hint fails to satisfy any route's `must` or `mustAll` regex conditions, resulting in an empty candidate list (`$sel`). The script then defaults to `meta.fallbackId` (typically `"R0"`). Verify that your hint matches the regex patterns defined for your target route and that no `exclude` rules are disqualifying it.

### How can I verify that my hint matches the regex patterns in routing.json?

Copy the `must` or `mustAll` regex strings from [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) into a PowerShell terminal and test them directly against your hint using the `-match` operator, or use an online regex tester. Ensure you account for the lowercasing applied by `$Hint.ToLowerInvariant()` before evaluation.

### What causes the "PRIMARY skill missing" error and exit code 2?

After selecting a primary route ID, the script constructs the absolute file path (`$skillAbs`) based on the route's `skill` field. If the referenced file does not exist at `skills/<skill>/SKILL.md`, the script terminates with exit code 2. Confirm the skill directory and file exist, and verify the path casing matches the repository structure.

### How do I debug routing decisions when the output lacks detail?

Run `master-route.ps1` with the `-Verbose` flag to expose internal variables, or execute `skills/scripts/test-routing.ps1` to validate your specific hint against the 162-case test matrix. For configuration issues, run `verify-routing-coherence.ps1` to detect JSON schema violations or orphaned priority entries that could skew routing logic.