CLAUDE CODE AGENTS: ADVANCED ORCHESTRATION - Chapter 8, Exercise 3
Fixing the Brief vs. Fixing the Agent's Definition
====================================================================================

QUESTION:
Explain the difference between fixing a problem by rewriting a single
brief and fixing a problem by revising an agent's own definition, and how
you would tell which one a given failure actually calls for.

SOLUTION / EXPLANATION:

Fixing a brief means changing what's given to the agent for one specific
task - the same agent definition (its system prompt, tools, and model
choice) stays exactly as it was; only the instructions for that particular
task get rewritten to be clearer or more complete. Fixing the agent's own
definition means changing the underlying, reusable configuration itself -
its system prompt, its allowed tools, or its chosen model - which then
affects every future task given to that agent, not just the one that just
failed.

This chapter gives a direct diagnostic test for telling which one a
failure actually calls for: give the SAME agent definition a new, improved
brief for the same or a similar task. If the improved brief now produces a
correct result, the original problem was the brief - a per-task issue,
fixed by writing better briefs going forward, with nothing wrong with the
agent's own underlying definition. If the same agent, given an already-good
brief, still produces the wrong kind of result - repeatedly, not just once
- the problem more likely lives in the agent's own definition itself, and
needs revising at that level (its system prompt's instructions, its tool
access, or its model), since better briefs alone aren't resolving it.

So the practical test isn't guessing based on how the failure felt - it's
running this specific experiment: hold the agent's definition fixed, vary
only the brief, and see whether the same kind of failure persists. A
failure that clears up with a better brief points to the brief; a failure
that persists despite an already-good brief points to the agent's own
definition.

--------------------------------------------------------------------------
WHY THIS WORKS AS AN ANSWER:
It defines both fixes precisely (per-task instructions vs. the reusable
underlying configuration) and then names the chapter's own concrete
diagnostic test (hold the definition fixed, improve only the brief, see if
the failure persists) as the actual way to distinguish which one a given
failure calls for, rather than a subjective guess.