# Fallback Behavior When a Task Is Unmatched in reverse-skill: Complete Guide

> Discover reverse-skill unmatched task fallback behavior. Learn how to create new skill modules and update routing for a structured workflow. Read the complete guide.

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

---

**When the reverse-skill platform encounters an unmatched task, it does not fall back to a hard-coded default but instead triggers a structured workflow requiring users to create a new skill module and update the canonical routing configuration.**

The **reverse-skill** framework by `zhaoxuya520` implements a strict, self-documenting routing architecture where every task dispatch decision flows from a single source of truth. Unlike traditional systems that rely on implicit default handlers, this repository enforces explicit route registration through [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json), ensuring complete transparency and traceability for all skill executions.

## How the reverse-skill Router Handles Unmatched Tasks

The platform-native router—implemented as **`master-route.ps1`** on Windows and **[`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh)** on Linux, macOS, or Kali—reads the **PRIMARY** routing table at runtime. When processing an incoming task, the router attempts to match the task against the `keywords` and `priority` fields defined in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json).

If no matching rule exists, the framework explicitly avoids hard-coded fallback tables or arbitrary default skills. Instead, the router halts execution and initiates the **fallback workflow**, directing the user to extend the framework through formal skill creation rather than bypassing the configuration.

## The Four-Step Fallback Workflow for Unmatched Tasks

The fallback behavior when a task is unmatched in reverse-skill follows a rigorous four-step process designed to maintain repository integrity and CI/CD coherence.

### Step 1: Propose a New Skill Module

When a route fails to match, the first action is to create a new skill module capable of handling the specific task. This involves establishing a new directory under `skills/` (e.g., `skills/my-new-skill/`) and implementing the platform-appropriate script (`my-new-skill.ps1` or [`my-new-skill.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/my-new-skill.sh)). This approach ensures that every supported capability exists as a version-controlled artifact rather than an inline hack.

### Step 2: Update the Canonical Routing Table

The new skill must be registered in **[`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)**, the sole authority for routing decisions. You must append a new route object containing the `label`, `skill` file path, `keywords` array, and `priority` integer. The router exclusively consumes this JSON file; no other configuration sources are consulted during task dispatch.

### Step 3: Add a Benchmark Case for CI Verification

To ensure the new route functions correctly in continuous integration pipelines, you must add a corresponding entry to **[`skills/config/routing-benchmark.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing-benchmark.json)**. This file contains test cases that verify each route, including fallbacks. The CI pipeline uses these benchmarks to validate that the routing logic remains coherent after your changes.

### Step 4: Regenerate Autogenerated Documentation

After modifying the JSON configuration, the framework regenerates auxiliary documentation including [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) and [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md). **Do not edit [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md) manually**—it serves only as an advisory reference generated from the canonical JSON source. This synchronization ensures the repository remains self-documenting and that documentation never diverges from actual routing behavior.

## CI Enforcement: Preventing Hard-Coded Fallbacks

The repository maintains strict architectural discipline through **`skills/scripts/verify-routing-coherence.ps1`**. This CI guard script actively rejects any pull requests containing hard-coded routing tables or missing entries in the canonical JSON files. By enforcing this policy, reverse-skill guarantees that the fallback behavior remains transparent and that no shadow routing logic can bypass the declared configuration in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json).

## Practical Implementation: Adding a Fallback Route

Below are platform-specific examples for implementing the fallback workflow when adding support for a previously unmatched task.

On Windows PowerShell:

```powershell

# Example: Adding a fallback for an unmatched task

# 1. Create a new skill directory (e.g., skills/my-new-skill)

# 2. Implement the skill logic (my-new-skill.ps1)

# 3. Register the skill in routing.json

$routingPath = Join-Path $PSScriptRoot '..\config\routing.json'
$routing = Get-Content $routingPath -Raw | ConvertFrom-Json

# Append a new route

$newRoute = @{
    label    = 'my-new-skill'
    skill    = 'my-new-skill.ps1'
    keywords = @('my', 'custom', 'task')
    priority = 42
}
$routing.routes += $newRoute
$routing | ConvertTo-Json -Depth 10 | Set-Content $routingPath -Encoding UTF8

# 4. Add a benchmark entry to routing-benchmark.json for CI verification

```

On Linux/macOS/Kali Bash:

```bash

# Example: Adding a fallback on Unix-like systems

# 1. Create a new skill folder (skills/my-new-skill)

# 2. Write the script (my-new-skill.sh)

# 3. Update routing.json using jq

jq '.routes += [{label:"my-new-skill",skill:"my-new-skill.sh",keywords:["my","custom","task"],priority:42}]' \
   skills/config/routing.json > tmp && mv tmp skills/config/routing.json

# 4. Add a corresponding entry to routing-benchmark.json

```

## Summary

- The **fallback behavior when a task is unmatched in reverse-skill** requires explicit skill creation rather than implicit defaults.
- **[`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)** serves as the single source of truth for all routing decisions, consumed by both `master-route.ps1` and [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh).
- The fallback workflow consists of four mandatory steps: propose skill, update routing table, add benchmark case, and regenerate documentation.
- CI enforcement via **`verify-routing-coherence.ps1`** prevents hard-coded routing tables and ensures configuration coherence.
- Documentation files like [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md) are autogenerated and should never be manually edited.

## Frequently Asked Questions

### What happens if reverse-skill cannot find a matching route for my task?

If the platform-native router cannot locate a matching entry in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json), execution halts and the system prompts you to create a new skill module. You must then follow the four-step fallback workflow to register the skill, add CI benchmarks, and regenerate documentation. No automatic default handler exists.

### Can I create a default skill to handle unmatched tasks automatically?

No. The reverse-skill framework explicitly prohibits default skills or hard-coded fallback tables. According to [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md), the "Route not matched → propose new skill" clause is strictly enforced. All capabilities must be explicitly declared in the JSON configuration and validated by `verify-routing-coherence.ps1`.

### How do I test a new skill route before submitting it?

You must add a benchmark entry to **[`skills/config/routing-benchmark.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing-benchmark.json)** that exercises your new route. The CI pipeline runs these benchmarks to verify routing coherence. Local testing involves manually invoking `master-route.ps1` or [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) with your task keywords to ensure the router selects your new skill from [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json).

### Where is the single source of truth for routing decisions in reverse-skill?

The canonical routing table resides at **[`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)**. Both the Windows router (`skills/scripts/master-route.ps1`) and Unix router ([`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh)) read exclusively from this file. No other configuration sources, environment variables, or hard-coded tables influence routing behavior.