CLAUDE CODE AGENTS: ADVANCED ORCHESTRATION - Chapter 3, Exercise 2
Two Documentation Agents, One Shared README
====================================================================================

QUESTION:
Two agents are launched in parallel to update documentation for two
different features. Both features happen to be documented in the same
single README file. Explain what could go wrong here, using this chapter's
own warning box.

SOLUTION / EXPLANATION:

This chapter's warning box is explicit that two agents can look
conceptually unrelated - here, documenting two genuinely different
features - while still sharing a hidden, real dependency through shared
state, such as both editing the same file. That's exactly the situation
described: the two features are conceptually separate, but "conceptually
separate" was mistaken for "genuinely independent," when the tasks are
not actually independent at the file level - both agents are reading from
and writing to the exact same README file at the same time.

The concrete risk is a race condition: if both agents read the README's
current content near the start of their own work, make their own edits
based on that shared starting point, and then each write their own updated
version back, one agent's changes can silently overwrite the other's -
whichever agent finishes and saves last effectively erases whatever the
other one added, with no error or warning that this happened. The final
README could end up missing one of the two documentation updates entirely,
even though both agents individually completed their task correctly from
their own point of view.

This is precisely the failure mode this chapter names as unique to
parallel execution - sequential execution wouldn't have this problem at
all, since only one agent would ever be reading or writing the file at any
given time, with the second agent starting from whatever the first agent
actually left behind. The fix here is either running these two agents
sequentially instead (since they share real state despite looking
conceptually unrelated), or restructuring the task so each agent works on
a genuinely separate portion of the file that doesn't overlap.

--------------------------------------------------------------------------
WHY THIS WORKS AS AN ANSWER:
It identifies the specific hidden dependency (both agents sharing the same
file) that apparent conceptual independence obscured, explains concretely
how a race condition produces a silently incomplete result, and names this
as exactly the parallel-specific risk the chapter's warning box describes.