reasoning-router

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-confidence conclusion.

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 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 signals
2. 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 allowed
4. Resolve conflicts:
   - Structure > domain (HOW > WHAT)
   - Complexity modulates depth AND tier
   - Ties: ALWAYS prefer lower token cost
5. Select primary + fallback
6. Present: "Using [method] — [why]. Fallback: [method]." (1 line)
7. Invoke with minimum viable totalThoughts
8. Monitor for stalls — escalate only on evidence

Token Cost Tiers

Tier 1 (lightest): aot-light, sequential-thinking
Tier 2 (moderate): structured-thinking, cascade-thinking, crash
Tier 3 (heavy):    shannon-thinking, atom-of-thoughts (full), think-strategies
Tier 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+ steps
2. Circular reasoning — same claim restated
3. Step overrun — exceeds 2× initial estimate
4. 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

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

When invoked with compare <problem>:

1. Classify the problem normally
2. Select 2-3 candidate methods (primary + 1-2 plausible alternatives)
3. Run each for 3-5 steps on the same problem
4. Compare: which produced higher-confidence findings with fewer tokens?
5. Present comparison table and recommend the winner
6. 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 (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.