# How to Add New Keyword Rules to routing.json Without Breaking Tests

> Learn how to add new keyword rules to routing.json without breaking tests. Synchronize route entries, skill files, priority arrays, and run verification tests for safe updates in zhaoxuya520/reverse-skill.

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

---

**To safely add new keyword rules to [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) in the zhaoxuya520/reverse-skill repository, you must synchronize four elements: the route entry, the matching skill markdown file, the priority array, and passing verification tests.**

The [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) file serves as the single source of truth for all routing logic in the reverse-skill system. Three PowerShell scripts—`master-route.ps1`, `verify-routing-coherence.ps1`, and `test-routing.ps1`—read this file directly at runtime. A comprehensive verification suite validates internal consistency, making strict adherence to the update protocol essential.

## Understanding the routing.json Structure

The [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) file contains two top-level objects:

- **`routes`** — a dictionary mapping route IDs to route definitions
- **`priority`** — an ordered array of route IDs determining match precedence

Each route requires three mandatory fields:

| Field | Description |
|-------|-------------|
| `label` | Human-readable description of the route |
| `skill` | Relative path to the skill markdown file |
| `keywords` | Array of keyword objects with filtering rules |

Keyword objects must include a `must` regular expression. Optional fields include `exclude` (negative match), `mustAll` (all patterns required), and `note` (documentation).

## Step-by-Step: Adding a New Keyword Rule

Follow this checklist in exact order to maintain test compliance.

### Step 1: Select an Unused Route Identifier

Choose a route ID not present in the existing `"routes"` object. For example, if `R40` exists, use `R41`.

### Step 2: Create the Route Entry

Add a new object under `"routes"` with complete field definitions.

```json
{
  "R41": {
    "label": "Network packet capture",
    "skill": "pcap-analysis/SKILL.md",
    "keywords": [
      {
        "must": "pcap|wireshark|tcpdump|packet.?capture|流量.?抓取",
        "note": "Matches raw network capture analysis requests"
      }
    ]
  }
}

```

### Step 3: Create the Corresponding Skill File

Ensure the `skill` path points to an existing, tracked file. Create [`pcap-analysis/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/pcap-analysis/SKILL.md) with appropriate content, or reference an existing markdown file.

### Step 4: Update the Priority Array

Insert the new route ID into `"priority"` at the desired precedence position. Higher-priority routes appear earlier in the array.

```json
"priority": [
  "R4", "R1", "R2", "R3", "R30", "R41", "R31", "R33", "R5"
]

```

In this example, `R41` matches before `R31` but after `R30`.

### Step 5: Run Verification Scripts

Execute the coherence validator:

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

```

Then run the quick regression suite:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/test-routing.ps1 -Quick

```

## What the Tests Validate

The `verify-routing-coherence.ps1` script enforces four invariants according to the source code:

1. **Route count minimum** — at least 30 routes must be defined
2. **Field completeness** — every route has `label`, `skill`, and `keywords`
3. **Skill file existence** — each `skill` path resolves to a tracked repository file
4. **Priority alignment** — the priority list contains exactly the same set of route IDs as the routes object (1-to-1 correspondence)

Failure on any check causes the router to fall back to the generic `R0` route, breaking expected routing behavior.

## Common Failure Modes and Fixes

| Symptom | Cause | Resolution |
|---------|-------|------------|
| "Priority mismatch" error | Route ID exists in `routes` but not `priority`, or vice versa | Ensure 1-to-1 correspondence between both structures |
| "Missing skill file" error | `skill` path points to non-existent or untracked file | Create the markdown file or correct the path |
| Route never matches | Priority position too low | Move the route ID earlier in the `priority` array |
| False positive matches | `must` regex too broad | Add `exclude` patterns or refine the regex |

## Key Files in the Routing System

- [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) — central routing definition read by all scripts
- `skills/scripts/verify-routing-coherence.ps1` — structural and logical validation
- `skills/scripts/test-routing.ps1` — regression testing with `-Quick` flag for fast feedback
- `skills/scripts/master-route.ps1` — runtime router that executes the matching logic

## Summary

- **Four elements must stay synchronized**: route entry, skill file, priority position, and test passage
- **Always run both verification scripts** before committing changes
- **Priority order determines match precedence**—place higher-specificity rules first
- **The `must` regex is mandatory** in every keyword object; use `exclude` to prevent false positives
- **Missing any step triggers fallback to `R0`**, breaking expected routing behavior

## Frequently Asked Questions

### What happens if I forget to update the priority array?

The `verify-routing-coherence.ps1` script detects the mismatch and reports a priority alignment error. The router will disregard the orphan route and may fall back to `R0` when processing queries that should match the new rule.

### Can I reuse an existing skill markdown file for a new route?

Yes. Multiple routes can reference the same `skill` path. This is useful when different keyword patterns should trigger identical behavior. The priority array still requires each route ID to be unique.

### How do I test my new route without running the full suite?

Use the `-Quick` flag with `test-routing.ps1`: `powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/test-routing.ps1 -Quick`. This runs essential validation without exhaustive regression scenarios.

### What regex features are supported in the `must` field?

Standard PowerShell/.NET regular expressions are supported, including alternation (`|`), quantifiers (`?`, `*`, `+`), character classes, and Unicode-aware patterns. The `?` quantifier pairs well with optional spacing patterns like `packet.?capture` to match both "packet capture" and "packetcapture".