reasoning-router
Classify problems and route to optimal thinking MCP (11 available). Monitor confidence, re-route on stall. Use for complex reasoning.
reasoning-router1539 wordsMITRepo-owned
Classify problems and route to optimal thinking MCP (11 available). Monitor confidence, re-route on stall. Use for complex reasoning.
Quick Start
Install:
npx skills add github:wyattowalsh/agents --skill reasoning-router -y -g --agent antigravity --agent claude-code --agent codex --agent crush --agent cursor --agent gemini-cli --agent github-copilot --agent grok --agent opencodeUse: /reasoning-router [problem or question]
Works with Claude Code, Gemini CLI, OpenCode, and other agentskills.io-compatible agents.
What It Does
Section titled “What It Does”Meta-reasoning layer: classify problems, dispatch to the optimal thinking MCP, monitor progress, re-route on stall. Minimize total tokens to a high-confidence conclusion.
$ARGUMENTS | Action |
|---|---|
| Problem or question text | Route — classify and dispatch to optimal thinking method |
compare <problem> | Compare — run 2-3 strategies on the same problem, pick best |
status | Status — show current thinking session state |
switch <method> | Switch — re-route to specified method mid-session |
recap | Recap — summarize reasoning so far across all methods used |
methods | Methods — show available methods with when-to-use cheatsheet |
| Empty | Guide — show routing cheatsheet and token tier table |
Critical Rules
Section titled “Critical Rules”- Always use the most advanced model —
model: opus. Never downgrade. - Minimize total tokens to conclusion — pick the lightest method that handles the problem. Escalate only on evidence of stall.
- Present routing decision before invoking — 1 line: method, why, fallback.
- Never invoke without classification — even if user names a method, validate fit.
- Carry forward on re-route — summarize findings ≤100 words, don’t restart.
- Simple gets simple — Tier 1 for simple problems, always. No exceptions.
- Token cost breaks ties — equal fit → lower tier wins.
- Start minimal, expand on evidence — lowest
totalThoughts, expand only when the tool requests more or stall detected. - One method at a time — no simultaneous thinking MCPs. Composition is sequential.
- Router ≠ thinker — classify, dispatch, monitor. Don’t duplicate reasoning.
- Respect tool workflows — creative-thinking: discover→plan→execute.
lotus-wisdom: start with
tag: begin. aot: useatomcommandsfor control. - Track token spend — note approximate tokens per session to refine routing.
Classification
Section titled “Classification”Run !uv run python skills/reasoning-router/scripts/problem-classifier.py "$ARGUMENTS"
for deterministic pre-scan, then refine with LLM judgment.
Axis 1 — Structure (what shape is the reasoning?)
Section titled “Axis 1 — Structure (what shape is the reasoning?)”| Structure | Signals | Primary Method |
|---|---|---|
| Decomposable | ”break down”, multi-hop, sub-questions | atom-of-thoughts |
| Sequential | ”step by step”, ordered process, debugging | sequential-thinking |
| Branching | ”explore options”, “what if”, alternatives | cascade-thinking |
| Constrained | ”given that”, requirements, formal specs | shannon-thinking |
| Interconnected | dependencies, circular, complex system | atom-of-thoughts (full) |
| Creative | ”brainstorm”, “novel”, “stuck”, “reframe” | creative-thinking |
| Contradictory | paradox, “both true”, tension, dilemma | lotus-wisdom |
| Investigative | ”why did”, root cause, debug, diagnose | crash |
Axis 2 — Complexity (how deep?)
Section titled “Axis 2 — Complexity (how deep?)”| Complexity | Signals | Depth Control |
|---|---|---|
| Simple (1-3 steps) | Short input, single concept, “quick” | Tier 1 ONLY: aot-light or sequential |
| Moderate (4-8 steps) | Multiple factors, some uncertainty | Default depth, structure-matched method |
| Complex (9+ steps) | Cross-domain, high uncertainty | Full depth, extended steps |
| Wicked (open-ended) | No clear solution, values conflict | Composition patterns allowed |
Axis 3 — Domain (what kind?)
Section titled “Axis 3 — Domain (what kind?)”| Domain | Method | Why |
|---|---|---|
| Engineering/architecture | shannon-thinking | Constraints → model → proof |
| Debugging | crash | Tool-aware investigation |
| Research | cascade-thinking | Parallel perspectives |
| Math/logic | atom-of-thoughts | Dependency DAG |
| Strategy | think-strategies | Strategy comparison |
| Creative/design | creative-thinking | Lateral techniques |
| Philosophy/ethics | lotus-wisdom | Non-dual integration |
| Planning | sequential-thinking | Linear progression |
| Pattern tracking | structured-thinking | Persistent memory |
Routing Algorithm
Section titled “Routing Algorithm”Optimize for minimum total tokens to reach a high-confidence conclusion.
1. Run problem-classifier.py for deterministic signals2. Score each axis (structure × complexity × domain)3. Apply efficiency gate: - Simple: ALWAYS Tier 1 (aot-light or sequential-thinking) - Moderate: structure-matched method at default depth - Complex: full method with extended depth - Wicked: composition patterns allowed4. Resolve conflicts: - Structure > domain (HOW > WHAT) - Complexity modulates depth AND tier - Ties: ALWAYS prefer lower token cost5. Select primary + fallback6. Present: "Using [method] — [why]. Fallback: [method]." (1 line)7. Invoke with minimum viable totalThoughts8. Monitor for stalls — escalate only on evidenceToken Cost Tiers
Section titled “Token Cost Tiers”Tier 1 (lightest): aot-light, sequential-thinkingTier 2 (moderate): structured-thinking, cascade-thinking, crashTier 3 (heavy): shannon-thinking, atom-of-thoughts (full), think-strategiesTier 4 (heaviest): creative-thinking, deep-lucid-3d, lotus-wisdomEfficiency Rules
Section titled “Efficiency Rules”- Never Tier 3-4 for a problem Tier 1-2 can handle
- Start with lowest viable
totalThoughts; expand only onneedsMoreThoughts cascade-thinking: start 2 branches max; add only if coverage insufficientcreative-thinking: usetimeframe: "quick"unless wickedthink-strategies: start withlinearorchain_of_thoughtbefore heavier strategies
Stall Detection
Section titled “Stall Detection”Read references/stall-detection.md when any stall signal fires.
4 stall signals:
- Confidence plateau — no increase >0.05 in 3+ steps
- Circular reasoning — same claim restated
- Step overrun — exceeds 2× initial estimate
- User signal — “try something else” or
/think switch
Re-routing by block type:
| Block | New Method | Why |
|---|---|---|
| Stuck in depth | cascade-thinking | Broaden |
| Too broad | atom-of-thoughts | Decompose |
| Too formal | creative-thinking | Reframe |
| Too abstract | crash | Ground in evidence |
| Contradictions | lotus-wisdom | Integrate |
| Wrong method | Reclassify | Start routing over |
Hard limits: Max 3 re-routes per session. Max 3× step estimate. No ping-pong (can’t return to a method already re-routed from). After 3 re-routes → recovery protocol: present findings, ask user to guide.
Composition Patterns
Section titled “Composition Patterns”Read references/composition-patterns.md for full protocols.
| Pattern | Sequence | When |
|---|---|---|
| Sketch→Detail | aot-light → aot (full) | Quick outline then deep dive |
| Diverge→Converge | creative-thinking → sequential | Generate options then evaluate |
| Explore→Formalize | cascade-thinking → shannon | Survey landscape then prove |
| Decompose→Investigate | aot → crash (per atom) | Break down then debug each |
| Analyze→Integrate | cascade-thinking → lotus-wisdom | Surface contradictions then synthesize |
| Strategize→Plan | think-strategies → sequential | Step back then plan forward |
Context transfer: At every method transition, produce ≤100 word summary of key findings with confidence scores. Carry claims, drop scaffolding.
When NOT to compose: Simple/moderate complexity, first method is converging, time pressure is high.
Compare Mode
Section titled “Compare Mode”When invoked with compare <problem>:
- Classify the problem normally
- Select 2-3 candidate methods (primary + 1-2 plausible alternatives)
- Run each for 3-5 steps on the same problem
- Compare: which produced higher-confidence findings with fewer tokens?
- Present comparison table and recommend the winner
- Continue with the winning method if user agrees
Methods Quick Reference
Section titled “Methods Quick Reference”When invoked with methods or for the routing cheatsheet:
| Method | MCP Tool | Tier | Sweet Spot |
|---|---|---|---|
| sequential-thinking | sequentialthinking | 1 | Linear, ordered reasoning |
| aot-light | aot-light | 1 | Quick atomic sketches |
| structured-thinking | capture_thought | 2 | Cross-session memory |
| cascade-thinking | cascade_thinking | 2 | Multi-perspective exploration |
| crash | crash | 2 | Debugging with tool integration |
| shannon-thinking | shannonthinking | 3 | Formal proof under constraints |
| atom-of-thoughts | aot + atomcommands | 3 | Deep decomposition with DAG |
| think-strategies | think-strategies | 3 | Named strategy frameworks |
| creative-thinking | discover_techniques → plan → execute | 4 | Lateral thinking (3-step required) |
| deep-lucid-3d | analyze_problem | 4 | Holistic UCPF analysis |
| lotus-wisdom | lotuswisdom (start: tag: begin) | 4 | Paradox and contradiction |
Read references/capability-map.md for full tool parameters and workflows.
Scope Boundaries
Section titled “Scope Boundaries”In scope: Problem classification, thinking MCP dispatch, stall detection, re-routing, composition pattern selection, method comparison.
Out of scope: Actually performing the reasoning (the thinking MCP does that), running tools or writing code (use appropriate skills), code review (honest-review), research (research), debugging implementation (use crash MCP directly).
Canonical Vocabulary
Section titled “Canonical Vocabulary”| Term | Meaning |
|---|---|
| method | A specific thinking MCP tool (e.g., cascade-thinking) |
| tier | Token cost classification (1=lightest, 4=heaviest) |
| structure | The shape of reasoning a problem requires |
| routing | Selecting the best method for a classified problem |
| stall | When a method stops making progress (confidence plateau, circular reasoning) |
| re-route | Switching to a different method mid-session |
| composition | Chaining 2+ methods sequentially for complex problems |
| efficiency gate | Override that forces Tier 1 methods for simple problems |
| context transfer | Summarizing findings when switching between methods |
| Field | Value |
|---|---|
| Source Type | repo-owned |
| Display Source | github:wyattowalsh/agents |
| Source Kind | repo |
| Installability | portable command |
| Review State | reviewed |
| Target Agents | antigravity, claude-code, codex, crush, cursor, gemini-cli, github-copilot, grok, opencode |
| Field | Value |
|---|---|
| Name | reasoning-router |
| License | MIT |
| Version | 0.1.0 |
| Author | wyattowalsh |
| Field | Value |
|---|---|
| Model | opus |
| Argument Hint | [problem or question] |
View Full SKILL.md
---name: reasoning-routerdescription: >- Classify problems and route to optimal thinking MCP (11 available). Monitor confidence, re-route on stall. Use for complex reasoning. NOT for simple questions (answer directly) or code review (honest-review).license: MITargument-hint: "[problem or question]"model: opusmetadata: author: wyattowalsh version: "0.1.0"---
# Reasoning Router
Meta-reasoning layer: classify problems, dispatch to the optimal thinking MCP,monitor progress, re-route on stall. Minimize total tokens to a high-confidenceconclusion.
Always uses the most advanced model (currently Opus 4.6). Meta-reasoning about*how to think* is the highest-leverage reasoning task.
## Dispatch
| `$ARGUMENTS` | Action ||---|---|| Problem or question text | **Route** — classify and dispatch to optimal thinking method || `compare <problem>` | **Compare** — run 2-3 strategies on the same problem, pick best || `status` | **Status** — show current thinking session state || `switch <method>` | **Switch** — re-route to specified method mid-session || `recap` | **Recap** — summarize reasoning so far across all methods used || `methods` | **Methods** — show available methods with when-to-use cheatsheet || Empty | **Guide** — show routing cheatsheet and token tier table |
---
## Classification
Run `!uv run python skills/reasoning-router/scripts/problem-classifier.py "$ARGUMENTS"`for deterministic pre-scan, then refine with LLM judgment.
### Axis 1 — Structure (what shape is the reasoning?)
| Structure | Signals | Primary Method ||-----------|---------|----------------|| **Decomposable** | "break down", multi-hop, sub-questions | `atom-of-thoughts` || **Sequential** | "step by step", ordered process, debugging | `sequential-thinking` || **Branching** | "explore options", "what if", alternatives | `cascade-thinking` || **Constrained** | "given that", requirements, formal specs | `shannon-thinking` || **Interconnected** | dependencies, circular, complex system | `atom-of-thoughts` (full) || **Creative** | "brainstorm", "novel", "stuck", "reframe" | `creative-thinking` || **Contradictory** | paradox, "both true", tension, dilemma | `lotus-wisdom` || **Investigative** | "why did", root cause, debug, diagnose | `crash` |
### Axis 2 — Complexity (how deep?)
| Complexity | Signals | Depth Control ||------------|---------|---------------|| **Simple** (1-3 steps) | Short input, single concept, "quick" | Tier 1 ONLY: `aot-light` or `sequential` || **Moderate** (4-8 steps) | Multiple factors, some uncertainty | Default depth, structure-matched method || **Complex** (9+ steps) | Cross-domain, high uncertainty | Full depth, extended steps || **Wicked** (open-ended) | No clear solution, values conflict | Composition patterns allowed |
### Axis 3 — Domain (what kind?)
| Domain | Method | Why ||--------|--------|-----|| **Engineering/architecture** | `shannon-thinking` | Constraints → model → proof || **Debugging** | `crash` | Tool-aware investigation || **Research** | `cascade-thinking` | Parallel perspectives || **Math/logic** | `atom-of-thoughts` | Dependency DAG || **Strategy** | `think-strategies` | Strategy comparison || **Creative/design** | `creative-thinking` | Lateral techniques || **Philosophy/ethics** | `lotus-wisdom` | Non-dual integration || **Planning** | `sequential-thinking` | Linear progression || **Pattern tracking** | `structured-thinking` | Persistent memory |
---
## Routing Algorithm
Optimize for **minimum total tokens to reach a high-confidence conclusion**.
```1. Run problem-classifier.py for deterministic signals2. Score each axis (structure × complexity × domain)3. Apply efficiency gate: - Simple: ALWAYS Tier 1 (aot-light or sequential-thinking) - Moderate: structure-matched method at default depth - Complex: full method with extended depth - Wicked: composition patterns allowed4. Resolve conflicts: - Structure > domain (HOW > WHAT) - Complexity modulates depth AND tier - Ties: ALWAYS prefer lower token cost5. Select primary + fallback6. Present: "Using [method] — [why]. Fallback: [method]." (1 line)7. Invoke with minimum viable totalThoughts8. Monitor for stalls — escalate only on evidence```
### Token Cost Tiers
```Tier 1 (lightest): aot-light, sequential-thinkingTier 2 (moderate): structured-thinking, cascade-thinking, crashTier 3 (heavy): shannon-thinking, atom-of-thoughts (full), think-strategiesTier 4 (heaviest): creative-thinking, deep-lucid-3d, lotus-wisdom```
### Efficiency Rules
- Never Tier 3-4 for a problem Tier 1-2 can handle- Start with lowest viable `totalThoughts`; expand only on `needsMoreThoughts`- `cascade-thinking`: start 2 branches max; add only if coverage insufficient- `creative-thinking`: use `timeframe: "quick"` unless wicked- `think-strategies`: start with `linear` or `chain_of_thought` before heavier strategies
---
## Stall Detection
Read `references/stall-detection.md` when any stall signal fires.
**4 stall signals:**1. **Confidence plateau** — no increase >0.05 in 3+ steps2. **Circular reasoning** — same claim restated3. **Step overrun** — exceeds 2× initial estimate4. **User signal** — "try something else" or `/think switch`
**Re-routing by block type:**
| Block | New Method | Why ||-------|-----------|-----|| Stuck in depth | `cascade-thinking` | Broaden || Too broad | `atom-of-thoughts` | Decompose || Too formal | `creative-thinking` | Reframe || Too abstract | `crash` | Ground in evidence || Contradictions | `lotus-wisdom` | Integrate || Wrong method | Reclassify | Start routing over |
**Hard limits:** Max 3 re-routes per session. Max 3× step estimate. No ping-pong(can't return to a method already re-routed from). After 3 re-routes → recoveryprotocol: present findings, ask user to guide.
---
## Composition Patterns
Read `references/composition-patterns.md` for full protocols.
| Pattern | Sequence | When ||---------|----------|------|| **Sketch→Detail** | `aot-light` → `aot` (full) | Quick outline then deep dive || **Diverge→Converge** | `creative-thinking` → `sequential` | Generate options then evaluate || **Explore→Formalize** | `cascade-thinking` → `shannon` | Survey landscape then prove || **Decompose→Investigate** | `aot` → `crash` (per atom) | Break down then debug each || **Analyze→Integrate** | `cascade-thinking` → `lotus-wisdom` | Surface contradictions then synthesize || **Strategize→Plan** | `think-strategies` → `sequential` | Step back then plan forward |
**Context transfer:** At every method transition, produce ≤100 word summary of keyfindings with confidence scores. Carry claims, drop scaffolding.
**When NOT to compose:** Simple/moderate complexity, first method is converging, timepressure is high.
---
## Compare Mode
When invoked with `compare <problem>`:
1. Classify the problem normally2. Select 2-3 candidate methods (primary + 1-2 plausible alternatives)3. Run each for 3-5 steps on the same problem4. Compare: which produced higher-confidence findings with fewer tokens?5. Present comparison table and recommend the winner6. Continue with the winning method if user agrees
---
## Methods Quick Reference
When invoked with `methods` or for the routing cheatsheet:
| Method | MCP Tool | Tier | Sweet Spot ||--------|----------|------|-----------|| sequential-thinking | `sequentialthinking` | 1 | Linear, ordered reasoning || aot-light | `aot-light` | 1 | Quick atomic sketches || structured-thinking | `capture_thought` | 2 | Cross-session memory || cascade-thinking | `cascade_thinking` | 2 | Multi-perspective exploration || crash | `crash` | 2 | Debugging with tool integration || shannon-thinking | `shannonthinking` | 3 | Formal proof under constraints || atom-of-thoughts | `aot` + `atomcommands` | 3 | Deep decomposition with DAG || think-strategies | `think-strategies` | 3 | Named strategy frameworks || creative-thinking | `discover_techniques` → `plan` → `execute` | 4 | Lateral thinking (3-step required) || deep-lucid-3d | `analyze_problem` | 4 | Holistic UCPF analysis || lotus-wisdom | `lotuswisdom` (start: `tag: begin`) | 4 | Paradox and contradiction |
Read `references/capability-map.md` for full tool parameters and workflows.
---
## Reference File Index
| File | Read When ||------|-----------|| `references/capability-map.md` | First invocation or unfamiliar with a tool's parameters || `references/routing-matrix.md` | Resolving routing conflicts, ties, or edge cases || `references/composition-patterns.md` | Problem needs a multi-tool sequence || `references/stall-detection.md` | Stall signal fires or session exceeds expected steps |
Load ONE reference at a time. Do not preload.
---
## Scope Boundaries
**In scope:** Problem classification, thinking MCP dispatch, stall detection,re-routing, composition pattern selection, method comparison.
**Out of scope:** Actually performing the reasoning (the thinking MCP does that),running tools or writing code (use appropriate skills), code review (honest-review),research (research), debugging implementation (use crash MCP directly).
---
## Canonical Vocabulary
| Term | Meaning ||------|---------|| method | A specific thinking MCP tool (e.g., cascade-thinking) || tier | Token cost classification (1=lightest, 4=heaviest) || structure | The shape of reasoning a problem requires || routing | Selecting the best method for a classified problem || stall | When a method stops making progress (confidence plateau, circular reasoning) || re-route | Switching to a different method mid-session || composition | Chaining 2+ methods sequentially for complex problems || efficiency gate | Override that forces Tier 1 methods for simple problems || context transfer | Summarizing findings when switching between methods |
---
## Critical Rules
1. **Always use the most advanced model** — `model: opus`. Never downgrade.2. **Minimize total tokens to conclusion** — pick the lightest method that handles the problem. Escalate only on evidence of stall.3. **Present routing decision before invoking** — 1 line: method, why, fallback.4. **Never invoke without classification** — even if user names a method, validate fit.5. **Carry forward on re-route** — summarize findings ≤100 words, don't restart.6. **Simple gets simple** — Tier 1 for simple problems, always. No exceptions.7. **Token cost breaks ties** — equal fit → lower tier wins.8. **Start minimal, expand on evidence** — lowest `totalThoughts`, expand only when the tool requests more or stall detected.9. **One method at a time** — no simultaneous thinking MCPs. Composition is sequential.10. **Router ≠ thinker** — classify, dispatch, monitor. Don't duplicate reasoning.11. **Respect tool workflows** — creative-thinking: discover→plan→execute. lotus-wisdom: start with `tag: begin`. aot: use `atomcommands` for control.12. **Track token spend** — note approximate tokens per session to refine routing.Resources
Section titled “Resources” Skill Catalog Browse custom and external skills.
CLI Reference Install and manage skills.
agentskills.io The open ecosystem for cross-agent skills.