# How to Add a New Routing Rule Without Breaking Existing Benchmarks

> Learn how to add a new routing rule without breaking benchmarks. Add a failing test case, update routing configs, and run local verification to ensure all tests pass.

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

---

**Add a failing benchmark case first, then update [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) and [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md), and finally run the local verification scripts to confirm all 173 test cases pass.**

The *reverse-skill* project routes every hint to the correct skill through a single **JSON-based routing system**. Adding a new routing rule requires syncing four files: the routing configuration, the benchmark suite, the documentation table, and the verification scripts. This guide walks through the exact workflow used in the `zhaoxuya520/reverse-skill` repository.

## The Routing Architecture

All routing decisions flow from **[`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)**. This file contains:

- A `routes` object mapping route identifiers to skill metadata
- A `priority` array defining match order
- Match criteria: `keywords`, `mustAll`, and `exclude` fields

Platform-specific routers—`skills/scripts/master-route.ps1` for Windows and [`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh) for Linux/macOS/Kali—parse this file at runtime to select the primary skill for a given hint.

The system enforces correctness through **three verification layers**:

- **Regression benchmark**: [`skills/tests/routing-benchmark.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tests/routing-benchmark.json) with 173 hint-to-route test cases
- **Coherence verification**: `skills/scripts/verify-routing-coherence.ps1` cross-checks JSON against documentation
- **CI enforcement**: [`.github/workflows/ci.yml`](https://github.com/zhaoxuya520/reverse-skill/blob/main/.github/workflows/ci.yml) runs all checks on every push

## Step-by-Step Workflow to Add a New Routing Rule

### Step 1: Create a Failing Benchmark Case

Before touching any routing logic, add a test case to [`skills/tests/routing-benchmark.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tests/routing-benchmark.json) that will fail until your new rule exists. This **test-driven approach** guarantees the benchmark catches implementation gaps.

```json
{
  "hint": "my new technique",
  "expect": "R99"
}

```

The benchmark runner will report "benchmark ghost expects" until the `R99` route resolves this hint correctly.

### Step 2: Edit [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json)

Insert the new route into [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json). Provide all required fields:

```json
{
  "routes": {
    "R99": {
      "label": "New Technique",
      "skill": "skills/new-technique/SKILL.md",
      "keywords": ["newtech", "exploit"],
      "mustAll": [],
      "exclude": []
    }
  },
  "priority": ["R0", "R1", "...", "R99"]
}

```

Critical: Append the route identifier to the `priority` array in the correct position. Higher-priority routes appear earlier; the first matching route wins.

### Step 3: Update [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md)

Add a corresponding row to [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) to maintain parity between machine-readable configuration and human documentation. The `verify-routing-coherence.ps1` script validates this alignment—mismatches trigger "routing.json route count suspicious" errors.

### Step 4: Run the Benchmark Locally

Execute the platform-appropriate test script before committing:

**Windows:**

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

```

**Linux/macOS/Kali:**

```bash
bash skills/scripts/test-routing.sh

```

All 173 cases must pass, including your new entry.

### Step 5: Commit and Push

The CI workflow defined in [`.github/workflows/ci.yml`](https://github.com/zhaoxuya520/reverse-skill/blob/main/.github/workflows/ci.yml) automatically re-runs the benchmark suite. Any regression—missing routes, priority misordering, or documentation drift—will block the build with specific error messages.

## Verification Scripts Reference

| Script | Purpose | Location |
|--------|---------|----------|
| `test-routing.ps1` / [`test-routing.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/test-routing.sh) | Execute 173-case benchmark suite | `skills/scripts/` |
| `verify-routing-coherence.ps1` | Validate JSON/MD alignment and route count consistency | `skills/scripts/` |

These scripts emit actionable diagnostics: "benchmark ghost expects" indicates a missing route implementation; "routing.json route count suspicious" signals documentation drift.

## Summary

- **Benchmark first**: Add failing test cases to [`routing-benchmark.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing-benchmark.json) before implementation
- **Single source of truth**: All route logic lives in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)
- **Triple sync required**: Match changes across JSON, benchmark, and [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md)
- **Local verification**: Run `test-routing.ps1` or [`test-routing.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/test-routing.sh) to catch regressions before CI
- **Clear diagnostics**: Error messages directly identify the inconsistency type

## Frequently Asked Questions

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

The router may select the wrong skill for ambiguous hints. The `verify-routing-coherence.ps1` script will not catch this specifically, but the benchmark in `test-routing.ps1` will fail when hints resolve to unexpected routes. Always verify your new case passes locally before pushing.

### Can I add multiple routing rules in one commit?

Yes, provided each rule has a corresponding benchmark case and [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) entry. The coherence script validates total route counts, so bulk updates are safe when all three files change atomically.

### Why does the benchmark use 173 fixed test cases?

This number represents the current regression coverage for all supported hint-to-route mappings in `zhaoxuya520/reverse-skill`. Adding a rule increments the count; the CI enforces that all historical cases continue passing, preventing silent behavioral changes to existing routing logic.

### What format should skill paths use in the `skill` field?

Use relative paths from the repository root: `skills/{skill-name}/SKILL.md`. The platform routers resolve these paths against the runtime working directory when loading skill documentation.