claude-code - 💡(How to fix) Fix [DOCS] Advisor tool: clarify mid-session course-correction value, not just upfront planning [1 participants]

Documentation Type

Unclear/confusing documentation

Documentation Location

https://docs.claude.com/en/docs/claude-code/sub-agents

Section/Topic

Advisor Tool - when to call it

Current Documentation

Minor nitpicking here perhaps

Current Documentation:
Docs say to call advisor before substantive work, before writing, before committing to an interpretation. Also lists "when stuck" but the main framing is upfront.

To clarify...

The advisor tool guidance frames it as a "before substantive work" tool : call it before writing, before committing to an interpretation, before building on an assumption. Also lists "when stuck" and "when considering a change of approach.

What's Wrong or Missing?

The "before you start" framing makes it feel like advisor is only for planning. I was helping someone fix bugs in a setup script and we went back and forth a bunch of times because Claude kept jumping to fixes without reading the errors properly. Calling advisor mid-session actually caught the mistakes and saved a ton of wasted tokens...

For me the wording can help out, the way docs are worded right now, you'd think I should've used it at the start, no point now.

So people probably skip it when they're already deep in a problem....which is exactly when it would help most!

To clarify...

The framing leads users (and the model itself) to treat advisor primarily as upfront planning. In practice, it's just as valuable mid-session for course correction, after going down a wrong path with conflicting information, after a series of failed fixes, or when conversation tokens are piling up without convergence.

In a session today, I ran into 4 bugs in setup.sh for an open source project. I went back and forth
multiple times swapping incorrect values in a config file because Claude jumped to fixes without reading errors
carefully. Calling advisor mid-session caught these mistakes and saved further token waste; but the docs framing made it feel like a "should have used it earlier" tool rather than a legitimate course-correction tool that's
valuable at any point.

Other users likely skip it when stuck because they assume "I should have called it earlier, too late now.

Suggested Improvement

Call advisor anytime, upfront or mid-session. Its especially useful when you're stuck, when fixes keep failing, or when you've gone down the wrong path. Earlier is better, but mid-session is still worth it.

Again to clarify ...

Add explicit guidance that advisor is equally valuable mid-session for course correction; not only as upfront planning. Suggested wording:

Call advisor at any point, not just before starting. It's especially useful mid-session when you've gone down the wrong path, when fixes aren't converging, or when you're about to declare done. The earlier the better, but mid-session course correction is a legitimate use, not a fallback.

Impact

Low - Minor confusion or inconvenience

Additional Context

I asked Claude if this was worth "Devs time"...

"Other users will skip the advisor when stuck mid-session because the docs frame it as a "before you start" tool. Clearer docs = more users get unstuck faster instead of burning tokens going down wrong paths like I did with you."