Troubleshooting Unexpected PRIMARY Skill Returns in master-route.ps1

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 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) should execute and writing the selection to 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 -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 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. A valid route may be skipped if a higher-priority route also matches the hint.

• Inspect $cfg.priority: Open 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 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 -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 -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 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 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.

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