Revise the plan when evidence changes

Learning objective

Revise investigation plans using intermediate findings and newly discovered questions.

Core idea

An investigation plan is a proposed route to an answer. When evidence changes the route, revise the next tasks rather than keep executing an obsolete checklist. Preserve the problem and acceptance criteria, but let observations determine which question to answer next.

Anthropic describes Claude Code’s agentic loop as gathering context, taking action, and verifying results. Tool results feed back into subsequent decisions. This makes adaptation operational: a failed test, a code search, or a file read can change the next action. Rewriting the plan without gathering or checking evidence is only a change in narrative.

See 1.6.1 for choosing adaptive decomposition and 1.2.4 for repairing gaps in research synthesis. This lesson concerns the investigation route before you have enough evidence to synthesize an answer: which hypothesis survives a finding, which task becomes unnecessary, and which unanswered question deserves the next tool call.

How it works

Anchor the plan in a symptom and a check

Anthropic’s best practices recommend describing a symptom, likely location, and what a fix looks like. Apply that structure before investigating. “Find why authentication fails after session timeout” is more useful than “review authentication.” A failing test or reproducible request gives the investigation a signal that can confirm or contradict its explanation.

Ask Claude to state the initial hypothesis and the evidence needed to test it. For example, a session-expiry defect might begin with a suspected refresh path. The first task is to inspect that path and the failing behavior, rather than edit the code to match the hypothesis immediately.

Use claude --permission-mode plan when you want research and a proposed implementation plan before source changes. Claude Code’s plan mode supports file reads and exploratory shell commands. It is a planning mode, not an unconditional command sandbox: shell handling depends on session configuration, and interactive terminal sessions with bypass permissions available have an exception to normal edit blocking.

For an interactive planning workflow, Ctrl+G opens the proposed plan in your text editor. When a discovery invalidates an implementation assumption, choose No, keep planning and explain the evidence that requires revision. Approval moves the session into the selected execution mode; it should follow a plan grounded in the investigation rather than substitute for one.

Convert a finding into a deciding question

A useful intermediate finding contains an observation and its consequence for the next task. “The token refresh code exists” is weak evidence. “The failing request never reaches token refresh because the cache returns a stale session first” changes the investigation route.

Use Read to inspect relevant code and Bash for repository searches or reproducible checks. The tool result enters Claude Code’s loop and informs the next decision. Name the exact source location or test output supporting the observation so a later step can distinguish evidence from an earlier guess.

Then ask a question whose answer changes the plan. If the cache can return an expired session, does its key distinguish sessions before and after renewal? If it does, investigate expiration handling. If it does not, inspect how that key is shared across the login and refresh paths. The observation identifies a branch; the follow-up question decides which branch needs work.

Anthropic’s common workflows recommend beginning with an overview and narrowing into relevant components. In an investigation, narrow according to the finding rather than traversing every directory. The next file should matter because it participates in the unexplained behavior.

Retire obsolete work as well as adding tasks

Adaptive investigation includes subtraction. When available, TaskCreate records a discovered task, TaskList lists tasks and their status, and TaskUpdate changes status, dependencies, or details, or deletes a task. If a check rules out a parser defect, use TaskUpdate to remove the obsolete rewrite and preserve the rejected hypothesis in the remaining investigation details. Otherwise, obsolete work keeps consuming context.

In Claude Code v2.1.268 and later, these tools are available by default only on Opus 4.7, Sonnet 4.6, Haiku 4.5, and earlier models. Other models require opt-in: export CLAUDE_CODE_ENABLE_TODO_TOOLS=1 before starting, name a task tool in --allowedTools, or include the task tools alongside your other tools in --tools. Background and cloud sessions provide them on every model. Subagents receive them only when the parent session has them. TodoWrite is disabled by default in favor of the Task tools; CLAUDE_CODE_ENABLE_TASKS=0 restores it in sessions with task-tracking tools.

Anthropic warns that unscoped exploration fills the main conversation. Specify a narrow question and request the evidence that answers it. For delegated exploration through Agent, see 1.3.2 and 1.3.3; return the deciding findings rather than the exploratory transcript.

Keep plan revisions tied to the original outcome. A discovered dependency can require additional investigation without authorizing an unrelated redesign. Ask Claude to explain which acceptance criterion the added task serves. If it cannot connect the task to the symptom or required behavior, defer that improvement from the investigation.

Verify the revised explanation

Claude Code can repeat context gathering, action, and verification as evidence arrives. Ask it to run the relevant check after a proposed correction, inspect the result, and revise again if the symptom persists. Anthropic recommends evidence such as the command and test output rather than a claim that the work succeeded.

A passing check supports only the behavior it exercises. If the original failure occurs after renewal but the test covers only initial login, the investigation still has an evidence gap. Revise the verification task to exercise renewal before accepting the explanation.

Distinguish a product failure from an unavailable check. A test that cannot run because a fixture is missing does not disprove the suspected code defect. The immediate follow-up is to establish usable verification or report that limitation, rather than declare the hypothesis resolved.

Only a passing check that exercises the original failure lets you accept the explanation.

Key distinctions and trade-offs

Plan revision versus goal revision: Evidence can change the files, hypotheses, and sequence required to answer a question. Changing the desired outcome is a separate scope decision. Do not let incidental discoveries redefine success silently.

Finding versus interpretation: A test failure or observed branch is evidence. Its proposed cause is an interpretation that needs checking. A plan built on an interpretation alone can move confidently in the wrong direction.

Adaptive investigation versus repeated broad search: Adaptation narrows or redirects work based on a result. Repeating “investigate the whole repository” increases context without stating what the next pass must resolve.

Planning adds overhead, which Anthropic advises avoiding for small changes whose approach is clear. Use it when uncertainty, unfamiliar code, or multi-file effects make premature editing expensive. After the evidence establishes a small correction, finish that correction and its verification rather than keep exploring for its own sake.

Architecture / decision scenario

A developer-productivity agent investigates failed login after session renewal. The initial plan is to inspect token refresh, reproduce the failure, and fix the refresh response if it is malformed.

The first check shows a valid refresh response. Reading the request path reveals that the next login reads a session cache before reaching the refreshed token. The agent retires the response-rewrite task and asks whether the cache key changes after renewal. A targeted search shows the key remains tied to the previous session identifier.

The revised plan inspects cache invalidation and its callers. That investigation discovers a second renewal path used by a background worker, so the verification plan gains a check for both callers. The agent proposes a correction that covers the shared behavior rather than fixing only the first observed path.

After implementation, it runs the reproduction and the two renewal checks, preserving the command results in its report. If either path still fails, the next task follows that result. The investigation ends when evidence supports the required behavior, rather than when every task from the first hypothesis has been executed.

Common exam traps

• Treating an initial hypothesis as a confirmed cause.
• Continuing a planned rewrite after evidence rules out its premise.
• Adding follow-ups without removing obsolete tasks.
• Expanding into unrelated improvements because investigation exposed them.
• Accepting a passing check that omits the original failure condition.
• Treating an unavailable test as a successful verification.

What to remember

Use findings to decide the next question, retire tasks whose assumptions failed, and preserve the original outcome. A revised plan earns confidence through source and verification evidence, not through a longer checklist.

Knowledge check

References

• Anthropic, How Claude Code works
• Anthropic, Best practices for Claude Code
• Anthropic, Common workflows
• Anthropic, Tools reference
• Anthropic, Permission modes