reasoning-strategy-selection · diff
v1.1 to v2.0
77 added, 68 removed. Audit A to A.
---
name: reasoning-strategy-selection
- description: Select and configure the right Reactive Agents reasoning strategy for task complexity, latency, and cost constraints.
- compatibility: Reactive Agents TypeScript projects using the reasoning layer.
+ description: Select and configure the right reasoning strategy, native FC behavior, and output quality pipeline for any task type.
+ compatibility: Reactive Agents TypeScript projects using @reactive-agents/*
metadata:
author: reactive-agents
- version: "1.1"
+ version: "2.0"
+ tier: "capability"
---
# Reasoning Strategy Selection
- Use this skill to pick and tune reasoning behavior before implementing task logic.
-
## Agent objective
- When implementing task-specific reasoning, generate code that:
+ Produce a `.withReasoning()` call with the correct strategy, iteration budget, and tool gates for the task — with output quality pipeline active when format matters.
- - Selects strategy based on complexity and uncertainty.
- - Keeps iteration budgets aligned with cost constraints.
- - Adds verification for high-stakes outputs.
+ ## When to load this skill
- ## What this skill does
+ - Before configuring `.withReasoning()` for any non-trivial agent
+ - When the task has specific quality, format, or tool-use requirements
+ - When choosing between strategies for cost vs. capability tradeoffs
- - Maps task types to `reactive`, `plan-execute`, `tree-of-thought`, `reflexion`, or `adaptive` strategies.
- - Balances confidence and token/cost budgets.
- - Recommends escalation and fallback rules for low-confidence outputs.
+ ## Implementation baseline
- ## Decision pattern
+ ```ts
+ // Default — adaptive works for most unknown workloads
+ const agent = await ReactiveAgents.create()
+ .withProvider("anthropic")
+ .withReasoning({
+ defaultStrategy: "adaptive",
+ maxIterations: 12,
+ })
+ .withTools()
+ .withVerification() // runtime output quality check
+ .withCostTracking({ perRequest: 0.30 })
+ .build();
+ ```
- 1. Start with `adaptive` for unknown workloads.
- 2. Use `reactive` for repetitive low-complexity tasks.
- 3. Use `plan-execute` for structured multi-step execution flows.
- 4. Use `tree-of-thought` for branching exploration of difficult problems.
- 5. Enable `enableStrategySwitching` when task complexity is unpredictable — automatically escalates on loop detection.
- 6. Add guardrails and verification when confidence is below thresholds.
+ ## Strategy selection guide
- ## Implementation baseline
+ | Task type | Strategy | Why |
+ |-----------|----------|-----|
+ | Simple Q&A, classification, extraction | `"reactive"` | Single-pass, minimal tokens |
+ | Multi-step with knowable plan upfront | `"plan-execute-reflect"` | Structured decomposition + reflection |
+ | Open-ended research, exploration | `"adaptive"` | Auto-escalates when stuck |
+ | Ambiguous problems needing exploration | `"tree-of-thought"` | Branch multiple paths, prune weak ones |
+ | Quality-critical iterative refinement | `"reflexion"` | Self-critique loop improves output |
+ | Unknown complexity | `"adaptive"` | Best safe default |
```ts
+ // NOTE: strategy name is "plan-execute-reflect" — NOT "plan-execute"
+ .withReasoning({ defaultStrategy: "plan-execute-reflect", maxIterations: 15 })
+
+ // Auto-switch strategy when agent gets stuck (loop detected)
.withReasoning({
defaultStrategy: "adaptive",
- maxIterations: 8,
- // Optional: auto-switch strategy if the agent gets stuck
- // enableStrategySwitching: true,
- // maxStrategySwitches: 2,
+ enableStrategySwitching: true,
+ maxStrategySwitches: 2,
+ fallbackStrategy: "plan-execute-reflect", // deterministic fallback (no LLM call)
})
- .withVerification()
- .withCostTracking()
```
- ## Strategy switching
+ ## Key patterns
- When `enableStrategySwitching: true`, the framework detects loop patterns (repeated tool calls, repeated thoughts, consecutive think-only steps) and automatically switches to a better strategy mid-run.
+ ### Required tools gate
+ Forces the agent to call specific tools before the final answer is accepted:
+
```ts
- // LLM evaluator picks the best strategy to switch to
- .withReasoning({ enableStrategySwitching: true, maxStrategySwitches: 2 })
+ .withTools()
+ .withRequiredTools({
+ tools: ["web-search"], // must be called at least once
+ maxRetries: 3, // retry if model skips
+ })
- // Deterministic switch — no LLM call, always switches to plan-execute-reflect
- .withReasoning({ enableStrategySwitching: true, fallbackStrategy: "plan-execute-reflect" })
+ // Adaptive mode — framework infers which tools are required from task phrasing
+ .withRequiredTools({ adaptive: true })
```
- Subscribe to `StrategySwitchEvaluated` and `StrategySwitched` EventBus events for observability.
-
- ## Code Examples
-
- ### Comparing Reasoning Strategies
-
- This example demonstrates how to specify a reasoning strategy for an agent. The `withReasoning` method allows you to set the `defaultStrategy` for the agent's thinking process.
+ ### Output quality pipeline
- The code iterates through a list of strategies (`reactive`, `plan-execute-reflect`, `adaptive`) and runs the same task with each one, showing how the choice of strategy can affect the outcome and the number of steps required.
+ The framework automatically extracts task intent (regex-based, no LLM call) and validates the output format. Supported `OutputFormat` values: `"markdown"`, `"json"`, `"csv"`, `"html"`, `"code"`, `"list"`, `"prose"`.
- *Source: [apps/examples/src/reasoning/19-reasoning-strategies.ts](apps/examples/src/reasoning/19-reasoning-strategies.ts)*
+ Hint the desired format in the task prompt and the pipeline validates + repairs if needed:
- ```typescript
- import { ReactiveAgents } from "@reactive-agents/runtime";
+ ```ts
+ // "return as JSON" → framework detects json format, validates output, repairs if needed
+ await agent.run("Analyse the data and return the results as JSON with keys: summary, score, flags");
+ ```
- const TASK = "Explain in one sentence why agent memory is important for multi-turn conversations.";
+ The `FinalizedOutput` shape: `{ output, formatValidated, synthesized, source, validationReason? }` — available in `result.metadata`.
- const strategies = [
- "reactive",
- "plan-execute-reflect",
- "adaptive",
- ] as const;
+ ### Observing strategy switches
- for (const strategy of strategies) {
- const agent = await ReactiveAgents.create()
- .withName(`strategy-${strategy}`)
- .withProvider("anthropic")
- .withReasoning({ defaultStrategy: strategy })
- .withMaxIterations(5)
- .build();
+ Subscribe to EventBus events to track strategy decisions:
- const result = await agent.run(TASK);
- console.log(`[${strategy}] ${result.metadata.stepsCount} steps: ${result.output}`);
- }
+ ```ts
+ agent.on("StrategySwitchEvaluated", (e) => console.log("Evaluating switch:", e));
+ agent.on("StrategySwitched", (e) => console.log("Switched to:", e.newStrategy));
```
- ## Expected implementation output
+ ## Builder API reference
- - A builder chain with explicit `.withReasoning({ defaultStrategy, maxIterations })`.
- - Strategy rationale tied to task type (reactive, plan-execute, tree-of-thought, reflexion, adaptive).
- - Validation checks for quality/cost tradeoffs under realistic prompts.
+ | Method | Key params | Default |
+ |--------|-----------|---------|
+ | `.withReasoning(opts?)` | `{ defaultStrategy?, maxIterations?, enableStrategySwitching?, maxStrategySwitches?, fallbackStrategy? }` | adaptive, 10 |
+ | `.withRequiredTools(cfg)` | `{ tools?: string[], adaptive?: boolean, maxRetries?: number }` | — |
+ | `.withMaxIterations(n)` | `number` | 10 |
+ | `.withVerification(opts?)` | `{ hallucinationDetection?, passThreshold?, useLLMTier? }` | — |
- ## Pitfalls to avoid
+ ## Pitfalls
- - Hard-coding expensive strategies for all tasks.
- - High iteration caps without budget enforcement.
- - Skipping verification on high-stakes outputs.
+ - `"plan-execute"` throws `StrategyNotFoundError` — the correct name is `"plan-execute-reflect"`
+ - `"reflexion"` is expensive — each iteration runs a self-critique LLM call; cap `maxIterations` at 6–8
+ - `"tree-of-thought"` spawns multiple branches — multiply expected token cost by branch factor
+ - `enableStrategySwitching: true` without `maxStrategySwitches` defaults to 2 — agent may not switch enough for complex tasks
+ - `withRequiredTools` without `withTools` does nothing — tools must be enabled first
+ - High `maxIterations` without `.withCostTracking()` can produce runaway costs on stuck agents