Chapter 5: Reasoning: How your agent decides what to do next
This introduction defines reasoning as producing an inspectable decision from clearly represented state and evidence, then frames how to choose an appropriate reasoning approach.
After this chapter you will be able to
- Stable execution-state meanings. Explain why reliable reasoning requires clear meanings for the facts and state supplied to the model, not just structured outputs from it.
- Inspectable decision boundary. Describe reasoning as the controlled transformation of a goal, current state, evidence, and constraints into an inspectable decision artifact, and distinguish that decision from permission to act.
- Inspectable decision artifact. Explain what a useful decision artifact records and how it lets the next component inspect and govern the decision.
- Reasoning and action boundary. Distinguish evidence-gathering actions within a bounded reasoning loop from consequential actions, and explain where their permissions belong.
- Three distinct reasoning artifacts. Distinguish private model reasoning, a visible decision record, and an action-and-evidence trace by what each reveals and what it cannot prove.
- Three waves of reasoning. Trace the shift from prompt-elicited steps, to trained reasoning models, to adaptive systems that allocate reasoning resources. Distinguish visible reasoning from proof of a model’s private computation.
- Budget and represented state. Explain why an architect must control both the reasoning budget and the represented state used for a decision, rather than relying on more deliberation alone.
- Evidence Available to Reasoning. Explain why model reasoning depends on the state and evidence the application supplies, including provenance needed to judge whether information is current or supported.
- Inspectable Decision Evidence. Distinguish provider-supplied reasoning summaries or encrypted traces from application-owned decision records and evidence traces.
- Portable Orchestration Control. Explain why explicit application orchestration remains useful when a provider can reason and use tools within one response.
- Flexible reasoning pattern selection. Explain that a run may use one, several, or no reasoning patterns, and that a precise external query can be cheaper and more reliable than a longer chain.
- Outcome and evidence first. Explain why reasoning quality is judged at the completed-task boundary, before examining the reasoning trace or step count.
- Confidence cost and trace telemetry. Describe how to assess confidence and operating costs, and distinguish recorded trace fields from a complete evaluation scorecard.
- Defined business correctness boundary. Explain why reasoning metrics depend on a definition of a correct business decision and when model reasoning may be unnecessary.
- Checkable decision dependencies. Explain how Chain-of-Thought represents a decision through intermediate claims that expose dependencies before the final answer, without requiring the model’s private scratchpad.
- Chain use and cost. Describe when to use or skip an explicit chain and why extra intermediate text alone does not justify its cost.
- Visible steps as decision records. Explain how an agent should use visible intermediate steps and why they should not be treated as a transcript of the model’s hidden computation.
- Three Chain-of-Thought variants. Distinguish zero-shot CoT, few-shot CoT, and process supervision by how each produces or checks intermediate steps. Explain why their relative cost and value must be measured on the target workload.
- Decision records and evidence traces. Distinguish an action-and-evidence trace from a decision record, using the support or coding example. Explain that Chain-of-Thought is worth its cost only when it makes the connection between evidence and the answer or change easier to inspect.
- Parseable stepwise reasoning record. Explain how the prompt makes reasoning steps inspectable: each step makes one claim, follows earlier steps or stated evidence, and reports confidence in that step. Describe why the fixed reply format matters to the application.
- Step-focused verification pass. Trace how the implementation chooses and challenges a reasoning step, and distinguish checking its logical transition from validating external evidence.
- Inspectable Argus review reasoning. Explain how Argus’s structured reasoning helps a reviewer inspect a code-review decision, and why a step’s score does not settle whether that step is correct.
- Faithfulness of visible chains. Explain why a visible Chain-of-Thought is not necessarily a faithful account of what drove an answer, and how to make its steps more reviewable.
- Choosing the next reasoning step. State when to use a single explicit chain, examples, a separate verifier, or evidence gathering instead of more chain text.
- Reasoning policy selection. Explain that Complexity-Based Routing selects a reasoning policy before committing resources, rather than sending every request down the same path. Describe the kinds of paths it may choose.
- Difficulty and consequence separation. Distinguish difficulty, which guides needed capacity, from consequence, which guides controls. Explain why surface length alone cannot determine either the reasoning path or whether risk overrides are needed.
- Router value and misroute costs. Describe when separate routing paths are worthwhile and why misroutes must be evaluated for different kinds of cost.
- Difficulty and consequence routing. Explain how difficulty selects a reasoning policy and why a consequential request can override that choice.
- Counterfactual routing evaluation. Explain how to test whether routing preserves acceptable outcomes and delivers real savings.
- Decision destination selection. Explain why routing should choose where a decision is made, not just which model runs. Describe the section’s examples: deterministic code for stable policy, a capable model for ambiguous judgment, a precise query for missing facts, and a person for undefined rules or consequential changes.
- Model effort versus application routing. Distinguish adaptive thinking and model effort controls from application routing. Explain that effort is a soft signal, max_tokens is an output ceiling, and the harness still makes decisions about complexity labels, false-simple rate, model selection, and consequence overrides.
- Three-tier routing table. Describe how the teaching router classifies a query as SIMPLE, MODERATE, or COMPLEX and uses the result to look up a model configuration. Explain why the table is declarative and the classifier prompt is short.
- Consequence policy boundary. Distinguish complexity classification from decisions about consequence, required evidence, authorization, and approval. State where production routing should handle consequential requests.
- Review depth and consequence. Explain how Argus chooses review depth without treating a small textual diff as necessarily low risk.
- Difficulty and consequence distinction. Distinguish a request’s difficulty from the consequences of acting on it, and explain why a stronger model addresses only the first concern.
- Routing value conditions. State when routing is worth using and when it should be skipped.
- Distinct candidates before commitment. Explain that Parallel Exploration preserves several materially different candidates before committing to one, and that “parallel” describes the reasoning topology rather than requiring simultaneous API calls.
- Branch cost decision. Justify using Parallel Exploration when distinct explanations or strategies remain plausible and early commitment would be expensive; explain why a cheap decisive query, duplicate branches, or no improvement over one path argues against it.
- Independent Branch Workflow. Trace how the payroll-policy question is split into distinct readings and a data check, with each branch producing evidence and a candidate result before convergence.
- Meaningful Branch Independence. Explain why branches must differ in what they investigate rather than merely run as separate agents or calls.
- Explicit Branching Controls. Distinguish inspectable, application-level Parallel Exploration from alternatives hidden inside one provider model call, and describe how to judge its added cost.
- Bounded branching and pruning. Explain how parallel exploration spends a bounded budget on alternatives and uses an explicit evaluator to decide which to pursue. Describe how Tree of Thoughts generates, scores, prunes, and expands candidate steps in the itinerary example.
- Candidate expansion and evaluation. Describe how the implementation generates candidate reasoning continuations and assigns values to partial paths. Explain why the expansion prompt asks for alternatives that differ in how they would be tested.
- UCT selection and backpropagation. Explain how node statistics support UCT selection and what backpropagation carries to ancestor nodes in this implementation.
- Evaluator error and safeguards. Explain how an LLM evaluator can favor a wrong branch or discard a correct minority branch, and describe the checks the section recommends.
- Meaningful branch diversity. Describe why many branches may still provide little coverage and how to make their differences consequential.
- Parallel exploration fit. Distinguish tasks worth parallel exploration from tasks that should stay single-path.
- Evidence Driven Hypothesis Loop. Explain how the agent tests an active hypothesis with an observation that could support or weaken it, then updates its explanation, changes direction, converges, or stops.
- Investigation Fit and Limits. Distinguish uncertain external causes that warrant bounded investigation from known transient failures that usually warrant deterministic retries, and state when investigation should stop.
- Evidence Driven Hypothesis Loop. Explain how Iterative Hypothesis Testing uses candidate hypotheses, predictions, observations, and evidence updates to guide an agent's next test. Distinguish this explicit investigation state from merely interleaving reasoning, actions, and observations.
- Evidence Based Continuation And Stopping. Explain when another cycle is worthwhile and when the agent should stop or escalate instead of repeating an operation.
- Coding Agent Debugging Loop. Trace how a coding agent reads failing output, proposes a cause, makes a bounded edit, runs a relevant check, examines the result, and revises if needed.
- Limits of Observed Evidence. Distinguish what a passing test or benchmark result supports from what it cannot establish, and explain why the loop should be validated against accepted outcomes.
- Hypothesis and experiment contracts. Describe the separate hypothesis state and experiment plan: a hypothesis records its status and evidence for and against it, while an experiment specifies an action and predicted observations both if the hypothesis holds and if it fails.
- Bounded investigation loop. Trace the investigation from an initial real observation through a bounded executable test, recording its actual observations and updating the hypothesis, to a stopping rule that may return inconclusive.
- Bounded fault verification. Explain how Argus can turn a suspected fault into a test plan while remaining within its permitted actions. Distinguish confirming a fault from being authorized to recover or repair it.
- Discriminating test evidence. Explain how to avoid tests that merely confirm an agent’s favored cause. Describe why tests should predict outcomes both when a hypothesis is true and when it is false, and should distinguish among candidate causes.
- Evidence-based stopping. Explain why repeated tests are not necessarily progress and what the agent should do when consecutive tests neither change the evidence nor eliminate a candidate.
- Safe testing and approach choice. Distinguish when to use an external-observation loop, a chain or deterministic computation, a bounded retry, or an evidence-rich handoff. Explain why tests with consequential side effects need appropriate permissions and why the model saying “done” does not establish acceptance.
- Reasoning contract and composition. Explain how a reasoning contract anchors the choice between deterministic handling, one reasoning pattern, and a composition of patterns.
- Evidence-driven reasoning paths. Describe how uncertainty, inexpensive evidence, and stable prior judgments can change the order of reasoning or eliminate model reasoning, while action consequences remain a separate concern.
- Meaningful branch independence. Explain why distinct frames, rather than more agents, make reasoning branches meaningfully independent, and describe when branching is worth using.
- Reasoning and collaboration boundary. Distinguish branches exploring one unresolved decision from agents collaborating on divided work or review, and compare the named patterns at that boundary.
- Task-appropriate review decisions. Explain how Argus varies review depth and makes selected decisions inspectable.
- Reasoning versus execution authority. Distinguish Argus’s ability to propose and check a fix from authority to make an unrestricted change.
What it builds on
- How information flows through cognitive modules (chapter 2) · Information flowing through an agent's cognitive modules.
- Set trust boundaries before granting autonomy (chapter 2) · Trust boundaries before granting an agent autonomy.
- The complete pattern map (chapter 2) · Introduces the two-dimensional pattern map in which this pattern sits at Reasoning × Route.
- The execution topology axis (chapter 2) · The execution topology axis provides context for the Reasoning × Parallel coordinate.
Section by section
Introduction
This introduction defines reasoning as producing an inspectable decision from clearly represented state and evidence, then frames how to choose an appropriate reasoning approach.
- Stable execution-state meanings: Explain why reliable reasoning requires clear meanings for the facts and state supplied to the model, not just structured outputs from it.
Why it matters: Clear inputs help prevent an agent from making decisions based on a mistaken account of what has happened. - Inspectable decision boundary: Describe reasoning as the controlled transformation of a goal, current state, evidence, and constraints into an inspectable decision artifact, and distinguish that decision from permission to act.
Why it matters: It keeps the agent's proposed next step distinguishable from an authorized action. - Reasoning approach fit: Explain why the reasoning approach should fit the task, evidence, cost, and consequence rather than simply maximize thinking depth.
Why it matters: It helps avoid spending effort on elaborate reasoning when evidence or risk calls for a different response.
Key terms: semantic protocol, execution facts, current state, control signals, reasoning, inspectable decision artifact, shared world, task, evidence, cost
5.1 What is reasoning? From represented state to an inspectable decision
This section defines the information a reasoning decision uses, what its decision artifact must preserve, and where evidence-gathering ends and action permissions begin.
- Reasoning decision inputs: Describe how the goal, current state, evidence, and constraints frame a reasoning decision. Distinguish a current observation from an assumption or old summary using source and timing information.
Why it matters: These inputs make clear what the agent is deciding, what it can rely on, and what limits apply. - Inspectable decision artifact: Explain what a useful decision artifact records and how it lets the next component inspect and govern the decision.
Why it matters: A decision others can inspect is easier to act on and govern than an unsupported answer. - Reasoning and action boundary: Distinguish evidence-gathering actions within a bounded reasoning loop from consequential actions, and explain where their permissions belong.
Why it matters: Calling something reasoning does not exempt its tool use or consequences from permission checks.
Key terms: goal, current state, evidence, constraints, decision artifact, uncertainty, next component, bounded reasoning loop, Action, Governance
5.1.1 Private reasoning, decision records, and execution traces
Distinguishes private model reasoning, visible decision records, and action-and-evidence traces, and explains what to retain when reviewing an agent’s decisions.
- Three distinct reasoning artifacts: Distinguish private model reasoning, a visible decision record, and an action-and-evidence trace by what each reveals and what it cannot prove.
Why it matters: Keeping these artifacts separate prevents an explanation or tool log from being mistaken for proof of how the model reasoned. - Production decision evidence: State what a production system should retain to review a decision, and explain the limited role of a visible rationale.
Why it matters: Retained inputs, configuration, and observed results give reviewers more to examine than the agent’s explanation alone.
Key terms: private model reasoning, visible explanation, decision record, action-and-evidence trace, represented input, model and effort configuration, decision artifact, tool results, tests, state transitions
5.1.2 How the reasoning landscape changed
This section traces three shifts in reasoning technology and argues that architects must control both reasoning effort and the state it operates on.
- Three waves of reasoning: Trace the shift from prompt-elicited steps, to trained reasoning models, to adaptive systems that allocate reasoning resources. Distinguish visible reasoning from proof of a model’s private computation.
Why it matters: The shift explains why reasoning design is no longer just a matter of writing a prompt. - Budget and represented state: Explain why an architect must control both the reasoning budget and the represented state used for a decision, rather than relying on more deliberation alone.
Why it matters: Spending more on reasoning helps little if the agent is reasoning from an unclear picture of the task.
Key terms: prompt-elicited reasoning, trained reasoning models, adaptive, budget-aware reasoning, visible reasoning, reasoning budget, represented state, evidence
5.1.3 What remains an architectural decision
The section explains why agent applications still need architectural reasoning controls even when models reason internally: the application controls the evidence, inspectable records, and orchestration around a decision.
- Evidence Available to Reasoning: Explain why model reasoning depends on the state and evidence the application supplies, including provenance needed to judge whether information is current or supported.
Why it matters: Good reasoning cannot compensate for missing evidence or context that hides where information came from. - Inspectable Decision Evidence: Distinguish provider-supplied reasoning summaries or encrypted traces from application-owned decision records and evidence traces.
Why it matters: An inspectable decision needs an application-controlled record, not an assumption that the provider's internal reasoning can be audited. - Portable Orchestration Control: Explain why explicit application orchestration remains useful when a provider can reason and use tools within one response.
Why it matters: Keeping control in the application lets you test decision boundaries even as models or providers change.
Key terms: represented state, evidence, harness, provenance, reasoning summary, summarized thinking, decision records, evidence traces, portable control, explicit orchestration
5.1.4 The reasoning patterns at a glance
The section explains that reasoning patterns are optional, can be combined within a run, and are not always preferable to a precise external query.
- Flexible reasoning pattern selection: Explain that a run may use one, several, or no reasoning patterns, and that a precise external query can be cheaper and more reliable than a longer chain.
Why it matters: It keeps you from adding reasoning steps when a simpler route would work better.
Key terms: reasoning patterns, router, hypothesis loop, chain, deterministic code, external query
5.1.5 Testing and observing reasoning
This section shows how to evaluate reasoning from accepted task outcomes and evidence, use traces to diagnose decisions, and recognize the limits of those metrics.
- Outcome and evidence first: Explain why reasoning quality is judged at the completed-task boundary, before examining the reasoning trace or step count.
Why it matters: It keeps an attractive-looking reasoning process from being mistaken for a trustworthy result. - Routing regret by consequence: Describe how to identify routing mistakes and why their consequences and operating context matter.
Why it matters: Not all routing errors have the same cost or risk. - Branch diversity and information gain: Explain what to measure in parallel branches and experiments, and what baseline to use.
Why it matters: Extra branches or tests are valuable only if they add distinct, useful information. - Confidence cost and trace telemetry: Describe how to assess confidence and operating costs, and distinguish recorded trace fields from a complete evaluation scorecard.
Why it matters: A trace helps diagnose a run, but it cannot by itself establish success or make confidence reliable. - Defined business correctness boundary: Explain why reasoning metrics depend on a definition of a correct business decision and when model reasoning may be unnecessary.
Why it matters: Measurement cannot resolve an undefined decision standard, and not every stable judgment needs a model.
Key terms: accepted result, evidence coverage, completed-task boundary, routing regret, false-simple outcomes, over-routing, diversity, information gain, refutation rate, baseline
5.2 Pattern: Chain-of-Thought
Introduces Chain-of-Thought as an application-owned sequence of checkable claims and explains when that structure is worth its cost.
- Checkable decision dependencies: Explain how Chain-of-Thought represents a decision through intermediate claims that expose dependencies before the final answer, without requiring the model’s private scratchpad.
Why it matters: Visible dependencies let another component check a consequential decision rather than trust its final answer alone. - Chain use and cost: Describe when to use or skip an explicit chain and why extra intermediate text alone does not justify its cost.
Why it matters: A chain is useful only when its checkable structure improves a decision enough to warrant the added work and latency.
Key terms: Chain-of-Thought, intermediate claims, dependency visibility, evidence references, private scratchpad, evidence, invariants, trigger, granularity, verification rule
5.2.1 Making the decision path explicit
This section treats visible Chain-of-Thought steps as inspectable decision records and compares three ways to produce or check them.
- Visible steps as decision records: Explain how an agent should use visible intermediate steps and why they should not be treated as a transcript of the model’s hidden computation.
Why it matters: A useful decision record is something you can inspect against evidence, not proof of what happened inside the model. - Three Chain-of-Thought variants: Distinguish zero-shot CoT, few-shot CoT, and process supervision by how each produces or checks intermediate steps. Explain why their relative cost and value must be measured on the target workload.
Why it matters: The three approaches create different artifacts and costs, so the right choice depends on the work your agent actually does.
Key terms: Chain-of-Thought, structured rationale, decision record, hidden computation, Zero-shot CoT, Few-shot CoT, process supervision, outcome supervision, target workload
5.2.2 In production: Separate the decision record from the action trace
The section distinguishes the evidence and actions an agent retains from the decision record that explains its choice.
- Decision records and evidence traces: Distinguish an action-and-evidence trace from a decision record, using the support or coding example. Explain that Chain-of-Thought is worth its cost only when it makes the connection between evidence and the answer or change easier to inspect.
Why it matters: Keeping the two records distinct lets a team inspect both what happened and why the agent chose its answer or change.
Key terms: action-and-evidence trace, decision record, Chain-of-Thought, private token trace
5.2.3 Building it
This section builds an application-visible reasoning record, uses step-level confidence to select a verification target, and handles malformed confidence ratings without guessing their scale.
- Parseable stepwise reasoning record: Explain how the prompt makes reasoning steps inspectable: each step makes one claim, follows earlier steps or stated evidence, and reports confidence in that step. Describe why the fixed reply format matters to the application.
Why it matters: A parseable record gives the application specific steps to inspect instead of only a final answer. - Step-focused verification pass: Trace how the implementation chooses and challenges a reasoning step, and distinguish checking its logical transition from validating external evidence.
Why it matters: A plausible answer can still contain an unsupported step, while a verification pass is not a substitute for checking facts. - Out-of-range confidence handling: Explain why an out-of-range confidence rating without a percent sign is recorded as unknown at 0.5 rather than rescaled by guessing, and how a bad conversion would affect step selection.
Why it matters: A chain and verification pass can appear to work while a scale-conversion mistake directs them at the wrong step.
Key terms: application-visible chain, COT_SYSTEM_PROMPT, one-claim-per-step, parse_chain, ReasoningStep, VERIFY_PROMPT, weakest_step, verify_chain, model-reported confidence, process supervision
5.2.4 Argus integration
This section shows how Argus makes code-review reasoning easier to inspect by decomposing its analysis and flagging a low-rated step.
- Inspectable Argus review reasoning: Explain how Argus’s structured reasoning helps a reviewer inspect a code-review decision, and why a step’s score does not settle whether that step is correct.
Why it matters: A score can focus review effort without replacing scrutiny of the evidence.
Key terms: structured reasoning, score, flagged dependency, evidence, verifier
5.2.5 When it breaks
This section explains when an explicit Chain-of-Thought helps, how it can fail, and when to use verification or gather more evidence instead.
- Faithfulness of visible chains: Explain why a visible Chain-of-Thought is not necessarily a faithful account of what drove an answer, and how to make its steps more reviewable.
Why it matters: A convincing explanation is not, by itself, evidence that the decision is sound. - Chain length and checkability: Distinguish chain collapse from chain inflation and explain the test for whether added structure helps.
Why it matters: More or less reasoning text is useful only if it makes the decision easier to inspect. - Limits of chain agreement: Explain what voting across independently sampled chains can show and why agreement does not establish truth.
Why it matters: Several agreeing explanations can still share the same error. - Choosing the next reasoning step: State when to use a single explicit chain, examples, a separate verifier, or evidence gathering instead of more chain text.
Why it matters: The right intervention depends on what is missing: a checkable decision path, stable structure, worthwhile verification, or external evidence.
Key terms: unfaithful chains, evidence, invariant, chain collapse, chain inflation, few-shot structure, self-consistency, independent chains, stability, correlated chains
5.3 Pattern: Complexity-Based Routing
Introduces Complexity-Based Routing as a way to choose a reasoning policy based on a request’s needs, while keeping difficulty separate from consequence and accounting for routing costs.
- Reasoning policy selection: Explain that Complexity-Based Routing selects a reasoning policy before committing resources, rather than sending every request down the same path. Describe the kinds of paths it may choose.
Why it matters: Choosing the path first lets the system match its resources and handling to the request. - Difficulty and consequence separation: Distinguish difficulty, which guides needed capacity, from consequence, which guides controls. Explain why surface length alone cannot determine either the reasoning path or whether risk overrides are needed.
Why it matters: A cheap reasoning path must not quietly bypass controls for a consequential action. - Router value and misroute costs: Describe when separate routing paths are worthwhile and why misroutes must be evaluated for different kinds of cost.
Why it matters: A router is beneficial only if its savings and better handling outweigh its overhead and mistakes.
Key terms: Complexity-Based Routing, reasoning policy, Reasoning × Route, difficulty, consequence, capacity, controls, risk overrides, classification overhead, misrouting cost
5.3.1 Route on difficulty, override on consequence
This subsection explains how to route reasoning by difficulty while letting consequences override the cheap path, and how to test whether routing actually pays off.
- Difficulty and consequence routing: Explain how difficulty selects a reasoning policy and why a consequential request can override that choice.
Why it matters: An easy-looking request may still need stricter handling because of its consequences. - Router choices and output: Describe the ways a routing decision can be made and what its output should record.
Why it matters: Recording the selected policy and override reason makes the routing decision inspectable. - Counterfactual routing evaluation: Explain how to test whether routing preserves acceptable outcomes and delivers real savings.
Why it matters: A cheap routing call is useful only if the overall system keeps acceptable results at a worthwhile cost.
Key terms: difficulty decision, consequence override, governed handling, lightweight classifier, selected policy, safety override, counterfactual, accepted outcomes, rescue, router cost
5.3.2 In production: Route the decision, not only the model
This section explains that routing should place each decision with the mechanism that can handle it reliably and affordably, rather than merely select a model or effort setting.
- Decision destination selection: Explain why routing should choose where a decision is made, not just which model runs. Describe the section’s examples: deterministic code for stable policy, a capable model for ambiguous judgment, a precise query for missing facts, and a person for undefined rules or consequential changes.
Why it matters: Choosing the right decision-maker can avoid both unnecessary model expense and unreliable automation. - Model effort versus application routing: Distinguish adaptive thinking and model effort controls from application routing. Explain that effort is a soft signal, max_tokens is an output ceiling, and the harness still makes decisions about complexity labels, false-simple rate, model selection, and consequence overrides.
Why it matters: A model’s thinking controls cannot substitute for an application’s routing and risk decisions. - Limits of production evidence: Distinguish evidence that a routing practice or model-choice interface exists from evidence that it performs well or reveals an internal routing policy.
Why it matters: Visible product behavior and adoption figures are useful examples, but neither validates an unseen routing design.
Key terms: planner-worker systems, deterministic code, capable model, precise query, adaptive thinking, effort controls, max_tokens, harness-level decisions, consequence override, current practice
5.3.3 Building it
This section builds a three-tier complexity router and explains its cost, classification, and policy boundaries.
- Three-tier routing table: Describe how the teaching router classifies a query as SIMPLE, MODERATE, or COMPLEX and uses the result to look up a model configuration. Explain why the table is declarative and the classifier prompt is short.
Why it matters: The router must make model selection cheap enough to be worth doing and easy to update. - Conservative complexity classification: Explain why the classifier avoids mistaking input length for difficulty and favors a safer tier when classification is uncertain.
Why it matters: These rules reduce the chance that an uncertain classification quietly sends a difficult request to an inadequate path. - Consequence policy boundary: Distinguish complexity classification from decisions about consequence, required evidence, authorization, and approval. State where production routing should handle consequential requests.
Why it matters: A difficulty tier alone cannot determine the safeguards a consequential request requires.
Key terms: SIMPLE, MODERATE, COMPLEX, classifier prompt, routing table, model configuration, tie-breaking rule, asymmetric recovery, ambiguous label, false simplicity
5.3.4 Argus integration
Shows how Argus routes code reviews by diff complexity while checking consequences separately, and how to evaluate the routed system against a baseline.
- Review depth and consequence: Explain how Argus chooses review depth without treating a small textual diff as necessarily low risk.
Why it matters: Review effort should reflect potential impact, not just the size of a change. - Routed review evaluation: Describe how to compare Argus's routed reviews with an unrouted baseline and when a percentage saving is justified.
Why it matters: A claimed saving is useful only if readers can see what was compared and whether review quality held up.
Key terms: router, review depth, diff's consequence, fast path, unrouted baseline, accepted defect findings, false-simple rescues, cost per accepted review, latency by class
5.3.5 When it breaks
This section explains when Complexity-Based Routing fails, how to keep difficulty separate from consequence, and when routing is worth using.
- Difficulty and consequence distinction: Distinguish a request’s difficulty from the consequences of acting on it, and explain why a stronger model addresses only the first concern.
Why it matters: Choosing a stronger model does not by itself make a consequential action safe. - Router cost and drift: Explain how classifier overhead and changing labels can undermine routing, and state when the router should be replayed.
Why it matters: Routing remains useful only if its cost and classifications still hold as the system changes. - Routing value conditions: State when routing is worth using and when it should be skipped.
Why it matters: A routing layer needs a demonstrable advantage over simply using the same path every time.
Key terms: false simplicity, difficulty, consequence, risk overrides, required evidence, governance, router overhead, drift, classifier, replay
5.4 Pattern: Parallel Exploration
This section introduces Parallel Exploration as a way to keep distinct reasoning candidates open and explains when the extra branch cost is justified.
- Distinct candidates before commitment: Explain that Parallel Exploration preserves several materially different candidates before committing to one, and that “parallel” describes the reasoning topology rather than requiring simultaneous API calls.
Why it matters: Keeping genuinely different options open can prevent an expensive premature commitment. - Branch cost decision: Justify using Parallel Exploration when distinct explanations or strategies remain plausible and early commitment would be expensive; explain why a cheap decisive query, duplicate branches, or no improvement over one path argues against it.
Why it matters: The pattern should earn its extra cost by finding value that a cheaper, simpler path would miss.
Key terms: Parallel Exploration, Reasoning × Parallel, candidates, topology, branch cost, single-path baseline, materially different, cheap precise query
5.4.1 A concrete branch decision: Independence before concurrency
This section shows how to explore genuinely independent alternatives, compare their evidence, and decide whether explicit branching is worth its cost.
- Independent Branch Workflow: Trace how the payroll-policy question is split into distinct readings and a data check, with each branch producing evidence and a candidate result before convergence.
Why it matters: Isolation lets alternatives develop before a common rule is used to judge their evidence. - Meaningful Branch Independence: Explain why branches must differ in what they investigate rather than merely run as separate agents or calls.
Why it matters: More branches help only when they test meaningfully different possibilities. - Explicit Branching Controls: Distinguish inspectable, application-level Parallel Exploration from alternatives hidden inside one provider model call, and describe how to judge its added cost.
Why it matters: Explicit controls make branching a design decision that can be inspected and compared with a simpler path. - Branch Budget Tradeoffs: Describe the pressures created by a branch budget and the rules to declare before adding concurrency.
Why it matters: A branch budget makes the costs and risks of exploring alternatives explicit before work runs concurrently.
Key terms: branch, evidence packages, convergence, acceptance rule, branch isolation, genuine independence, separate agent contexts, explicit tree nodes, repeated constrained calls, Parallel Exploration
5.4.2 Branching, scoring, and pruning
This section explains how parallel reasoning preserves alternatives, evaluates them, and prunes or combines branches within a bounded budget.
- Bounded branching and pruning: Explain how parallel exploration spends a bounded budget on alternatives and uses an explicit evaluator to decide which to pursue. Describe how Tree of Thoughts generates, scores, prunes, and expands candidate steps in the itinerary example.
Why it matters: Scoring before expansion helps an agent spend its reasoning budget on more promising options. - Alternative reasoning structures: Distinguish trees, graphs, and small portfolios as ways to preserve alternatives, and describe what Graph of Thoughts adds to a tree. Explain why a reported improvement from extra branching does not guarantee it is worthwhile for another workload.
Why it matters: It keeps the choice of reasoning structure tied to the task rather than to a benchmark result alone. - MCTS adaptation and evidence: Describe the section’s software-engineering example of Monte Carlo Tree Search and distinguish its reported result from the chapter’s smaller implementation.
Why it matters: The distinction prevents a benchmark result for SWE-Search from being mistaken for a result demonstrated by the compact implementation.
Key terms: parallel exploration, Tree of Thoughts, pruning, explicit evaluator, Graph of Thoughts, Adaptive Graph of Thoughts, portfolio, disciplined convergence rule, Monte Carlo Tree Search, SWE-Search
5.4.3 Building it
This section shows how a compact Monte Carlo Tree Search implementation expands, scores, and selects LLM reasoning paths while guarding against misleading scores.
- Candidate expansion and evaluation: Describe how the implementation generates candidate reasoning continuations and assigns values to partial paths. Explain why the expansion prompt asks for alternatives that differ in how they would be tested.
Why it matters: Branches are useful only when they explore meaningfully different possibilities, and their early scores are estimates rather than completed results. - UCT selection and backpropagation: Explain how node statistics support UCT selection and what backpropagation carries to ancestor nodes in this implementation.
Why it matters: The search can revisit promising paths without abandoning less-explored ones, but its propagated values must not be treated as verified outcomes. - Score parsing safeguard: Explain why a score outside 0.00 to 1.00 without a percent sign is treated as unknown rather than clamped.
Why it matters: A malformed score should not steer the search toward a branch that only appears strong because of a parsing mistake.
Key terms: expand, evaluate, ThoughtNode, branch budget, UCT, visit count, cumulative score, backpropagation, LLM value estimate, _parse_score
5.4.4 When it breaks
Explains when Parallel Exploration is worth its compute cost and how evaluator error and shallow breadth can undermine it.
- Evaluator error and safeguards: Explain how an LLM evaluator can favor a wrong branch or discard a correct minority branch, and describe the checks the section recommends.
Why it matters: Exploring alternatives does not help if the comparison discards the right one. - Meaningful branch diversity: Describe why many branches may still provide little coverage and how to make their differences consequential.
Why it matters: More branches are useful only if they explore alternatives that could lead to different tests or conclusions. - Parallel exploration fit: Distinguish tasks worth parallel exploration from tasks that should stay single-path.
Why it matters: This trade-off helps avoid paying for branching when a simpler path is sufficient.
Key terms: evaluator error, correct minority branch, executable checks, domain rules, separately validated judge, shallow breadth, branches, token multiplication, coverage, Parallel Exploration
5.5 Pattern: Iterative Hypothesis Testing
Introduces Iterative Hypothesis Testing as a bounded reasoning loop in which discriminating observations can change an agent’s explanation of an uncertain external state.
- Evidence Driven Hypothesis Loop: Explain how the agent tests an active hypothesis with an observation that could support or weaken it, then updates its explanation, changes direction, converges, or stops.
Why it matters: A test is useful only if its result can affect what the agent believes or does next. - Investigation Fit and Limits: Distinguish uncertain external causes that warrant bounded investigation from known transient failures that usually warrant deterministic retries, and state when investigation should stop.
Why it matters: Choosing when to investigate—and when to stop—keeps reasoning useful and bounded. - Backward GIS Investigation: Trace how the blank-globe symptom motivates checks at different stages of the GIS toolchain rather than another render of unchanged state.
Why it matters: Checking separate stages can reveal a hidden upstream fault that repeating the visible failure cannot. - Investigation Authority Boundary: Explain why investigative queries and sandboxed tests should have only the authority they need, while changes such as restarting or mutating data require separate authorization.
Why it matters: An agent can gather evidence without treating permission to investigate as permission to alter the system.
Key terms: Iterative Hypothesis Testing, Reasoning × Loop, discriminating observation, active hypothesis, external state, bounded experiment, deterministic retry policy, budget, stopping rule, GIS toolchain
5.5.1 The hypothesis-experiment loop
This section explains how an agent can investigate with explicit hypotheses and evidence, while avoiding unproductive repetitions and unjustified confidence.
- Evidence Driven Hypothesis Loop: Explain how Iterative Hypothesis Testing uses candidate hypotheses, predictions, observations, and evidence updates to guide an agent's next test. Distinguish this explicit investigation state from merely interleaving reasoning, actions, and observations.
Why it matters: Explicit hypotheses make it possible to tell whether an experiment actually changed the agent's explanation. - Evidence Based Continuation And Stopping: Explain when another cycle is worthwhile and when the agent should stop or escalate instead of repeating an operation.
Why it matters: A stopping rule keeps investigation from becoming repeated work with no new evidence. - Persistent Evidence And Confidence: Describe why hypotheses, observations, errors, and tool results must persist across calls, and how the agent should guard against confidence drift.
Why it matters: Keeping the actual results visible prevents repeated effort from being mistaken for stronger evidence.
Key terms: Iterative Hypothesis Testing, candidate hypotheses, predictions, evidence updates, ReAct, back-edge, bounded retry, evidence-rich handoff, stopping rules, explicit state
5.5.2 In Production: How coding agents actually debug
Shows how coding agents debug through a hypothesis-and-test loop, while distinguishing observable results from claims about reasoning or overall reliability.
- Coding Agent Debugging Loop: Trace how a coding agent reads failing output, proposes a cause, makes a bounded edit, runs a relevant check, examines the result, and revises if needed.
Why it matters: The check gives the agent evidence for whether its proposed fix worked. - Limits of Observed Evidence: Distinguish what a passing test or benchmark result supports from what it cannot establish, and explain why the loop should be validated against accepted outcomes.
Why it matters: It keeps a successful check from being mistaken for proof that the investigation or the system is reliable in every respect. - Pattern Composition and Permission: Describe how routing, parallel causes, and a claim-and-evidence record can fit within the debugging loop without granting permission to change production state.
Why it matters: An investigation can become more structured without crossing the boundary between reasoning and authorized action.
Key terms: observe, root cause, experiment, gather evidence, revise, external result, acceptance condition, SWE-bench, design hypothesis, accepted outcomes
5.5.3 Building it
This section shows how to implement hypothesis testing with explicit hypothesis and experiment records, evidence updates, and a bounded investigation loop.
- Hypothesis and experiment contracts: Describe the separate hypothesis state and experiment plan: a hypothesis records its status and evidence for and against it, while an experiment specifies an action and predicted observations both if the hypothesis holds and if it fails.
Why it matters: Predicting both outcomes makes a test capable of challenging a hypothesis, not just confirming it. - Evidence update limitations: Explain what the demo's evidence_ratio does and why production evidence assessment needs more than a count of supporting and opposing observations.
Why it matters: A visible evidence count should not be mistaken for a trustworthy assessment of the hypothesis. - Bounded investigation loop: Trace the investigation from an initial real observation through a bounded executable test, recording its actual observations and updating the hypothesis, to a stopping rule that may return inconclusive.
Why it matters: A bounded loop grounded in actual observations can stop honestly when the available tests do not settle the question.
Key terms: Hypothesis, Experiment, active, supported, refuted, evidence_ratio, provenance, domain-specific evidence rules, initial observation, bounded executable action
5.5.4 Argus integration
Argus uses hypothesis testing to check a suspected fault within a bounded sandbox, without gaining permission to repair it.
- Bounded fault verification: Explain how Argus can turn a suspected fault into a test plan while remaining within its permitted actions. Distinguish confirming a fault from being authorized to recover or repair it.
Why it matters: Finding a fault and having permission to fix it are separate decisions.
Key terms: hypothesis testing, bounded test plan, execute_fn, sandboxed checks, recovery
5.5.5 When it breaks
This section explains how iterative hypothesis testing can fail and when to test, retry, use a simpler approach, or stop.
- Discriminating test evidence: Explain how to avoid tests that merely confirm an agent’s favored cause. Describe why tests should predict outcomes both when a hypothesis is true and when it is false, and should distinguish among candidate causes.
Why it matters: A test that only supports the agent’s first guess may leave the real cause undiscovered. - Evidence-based stopping: Explain why repeated tests are not necessarily progress and what the agent should do when consecutive tests neither change the evidence nor eliminate a candidate.
Why it matters: A stopping rule keeps an agent from mistaking repeated activity for a better-grounded decision. - Safe testing and approach choice: Distinguish when to use an external-observation loop, a chain or deterministic computation, a bounded retry, or an evidence-rich handoff. Explain why tests with consequential side effects need appropriate permissions and why the model saying “done” does not establish acceptance.
Why it matters: Choosing the right approach prevents unnecessary loops and keeps diagnostic actions from causing harm.
Key terms: Confirmation bias, predictions, observations, candidates, Confidence drift, evidence, hypothesis set, handoff, Environmental damage, Blast Radius Control
5.6 Composing reasoning patterns around the decision
This section shows how to combine reasoning patterns around a shared decision contract, choose their order from evidence and uncertainty, and judge the complete run rather than treating deeper reasoning as inherently better.
- Reasoning contract and composition: Explain how a reasoning contract anchors the choice between deterministic handling, one reasoning pattern, and a composition of patterns.
Why it matters: A shared contract lets you combine patterns to serve a particular decision instead of following a fixed escalation ladder. - Evidence-driven reasoning paths: Describe how uncertainty, inexpensive evidence, and stable prior judgments can change the order of reasoning or eliminate model reasoning, while action consequences remain a separate concern.
Why it matters: The cheapest decisive evidence may simplify reasoning, but it does not remove controls on consequential actions. - Whole-run optimization criteria: Explain why reasoning compositions should be judged by outcomes and decisive evidence rather than by how elaborate or inexpensive a single pattern appears.
Why it matters: Whole-run measures reveal whether added reasoning actually improves decisions enough to justify its cost. - Fresh versus resumable workers: Distinguish when an isolated fresh reasoning worker is preferable to a resumable one, and describe the state-management choice this creates.
Why it matters: Choosing what a worker carries forward protects a new investigation from stale assumptions without discarding costly context unnecessarily.
Key terms: reasoning contract, Complexity-Based Routing, reasoning topology, cheap external evidence, deterministic recovery, replay tests, consequence, cost per accepted outcome, time to decisive evidence, false convergence
5.7 Reasoning branches and collaboration
This section explains how to create meaningful reasoning branches and where branching ends and collaboration begins.
- Meaningful branch independence: Explain why distinct frames, rather than more agents, make reasoning branches meaningfully independent, and describe when branching is worth using.
Why it matters: This helps you seek genuinely different reasoning paths without paying for extra agents that add no value. - Reasoning and collaboration boundary: Distinguish branches exploring one unresolved decision from agents collaborating on divided work or review, and compare the named patterns at that boundary.
Why it matters: The distinction helps you choose between exploring a decision and coordinating separate responsibilities.
Key terms: branch independence, distinct frame, authoritative evidence, convergence rule, Parallel Exploration, Collaboration, Fan-Out/Gather, Adversarial Review
5.8 Argus checkpoint: What the agent can do now
This checkpoint summarizes the inspectable reasoning Argus can perform and the limits on what it can execute.
- Task-appropriate review decisions: Explain how Argus varies review depth and makes selected decisions inspectable.
Why it matters: It shows what the added reasoning capabilities change about Argus’s reviews. - Bounded checks and review signals: Describe the checks and diagnostic signals Argus can provide without treating its self-ratings as evidence.
Why it matters: These signals help inspect a review without mistaking model confidence for proof. - Reasoning versus execution authority: Distinguish Argus’s ability to propose and check a fix from authority to make an unrestricted change.
Why it matters: An inspectable decision does not, by itself, authorize real-world changes.
Key terms: inspectable decisions, appropriate depth, claim-and-dependency chain, bounded sandbox checks, evidence interface, telemetry schema, low self-ratings, actual evidence, teaching system, production state
5.9 Summary
5.10 References
This section lists the sources cited in the chapter on agent reasoning.
Where this is used later
- What is action? (chapter 6) · Addresses the separate boundary where a decision becomes an action with consequences.
- The interruption test (chapter 6) · Distinguishes reasoning toward a decision from executing the resulting plan.
- What is governance? Autonomy without accountability is a liability (chapter 9) · Governance determines which consequences the agent may create.
- Evaluation belongs beside the change (chapter 7) · Evaluation needs accepted outcomes and evidence as its starting point.
- Pattern: Approval Gate (chapter 9) · Approval controls address consequential actions that model selection alone cannot make safe.
- Pattern: Blast Radius Control (chapter 9) · Containment controls limit the effects of consequential actions.
- Risk follows the effect (chapter 6) · Develops how action risk follows the effect.
- Recovery requires permission and responsibility (chapter 7) · The later discussion of recovery permissions builds on the distinction between verifying a fault and being authorized to act on it.
Concepts explained in this chapter
- decision recordAn inspectable record of a decision or conclusion and its supporting evidence, assumptions, and rationale.
- reasoningAn agent capability for evaluating information, forming hypotheses, and selecting conclusions or actions.
- iterative hypothesis testingAn evaluation pattern in which successive passes propose hypotheses and test them against evidence.
- complexity-based routingA routing pattern that selects an agent's reasoning policy and resource path according to request properties such as difficulty and consequence.
- chain-of-thoughtA reasoning technique that represents a decision as a sequence of intermediate steps or claims.
- evidence coverageThe extent to which decisive claims in a result are linked to the evidence required to support them.
- agent loopAn iterative agent-control pattern in which an agent perceives, reasons, acts, and reflects, with subsequent steps selected dynamically.
- ArgusArgus is the code review agent built as the book's progressively developed reference system.
- hypothesis testingAn analytical technique that evaluates candidate explanations or predictions against evidence or observations.
- verifierA verifier is a component that checks whether an answer or result satisfies relevant criteria.
- process supervisionProcess supervision evaluates intermediate steps in a problem-solving process rather than assessing only its final answer.
- governanceThe agent capability and control framework for enforcing policies, constraints, oversight, and accountability.
- reasoning depthReasoning depth is the amount of deliberate analysis and computational effort an agent allocates to a problem before acting or responding.
- trajectoryA record of events and operations during a system run, arranged to show its progression and support diagnosis.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.
