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

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, 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 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.

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). 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, 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. 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 and routing.md. Do not edit 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.

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:

# 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:

# 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 serves as the single source of truth for all routing decisions, consumed by both master-route.ps1 and 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 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, 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, 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 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 with your task keywords to ensure the router selects your new skill from 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. Both the Windows router (skills/scripts/master-route.ps1) and Unix router (skills/scripts/master-route.sh) read exclusively from this file. No other configuration sources, environment variables, or hard-coded tables influence routing behavior.

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