CLAUDE CODE AGENTS: FUNDAMENTALS - Chapter 9, Exercise 3
Why Accurately Documenting a Bug Isn't a Documentation Failure
====================================================================================

QUESTION:
A documentation agent accurately documents a function that actually
contains a bug, describing its current (buggy) behavior correctly. A
developer says this means the documentation agent failed at its job. Using
this chapter's own warning box, explain why this criticism is misplaced.

SOLUTION / EXPLANATION:

This chapter's warning box is explicit that accurate documentation is not
the same as validated correctness, and states directly that documenting
something is not the same as reviewing or validating it - that's a
code-review agent's job (Chapter 6), not a documentation agent's.

The documentation agent's actual job, as this chapter defines it, is to
describe what the code ACTUALLY does, verified against the real current
implementation - not what the code was intended to do, or what it should
ideally do. If the function genuinely contains a bug, then the "actual
behavior" of that function includes that buggy behavior, and documenting it
correctly means describing exactly that - including the bug - rather than
describing some idealized, bug-free version of behavior the code doesn't
actually exhibit. Describing the buggy behavior accurately is precisely
what correct, honest documentation looks like in this situation.

The developer's criticism conflates two separate responsibilities: judging
whether the code's behavior is CORRECT (which belongs to a code-review or
testing agent) versus describing what the code's behavior actually IS
(which is the documentation agent's actual job). The documentation agent
did its own job correctly - the code itself has the problem, not the
documentation describing it accurately. Faulting the documentation agent
for the underlying bug is faulting the wrong step in the process.

--------------------------------------------------------------------------
WHY THIS WORKS AS AN ANSWER:
It identifies precisely which responsibility belongs to which agent
(describing actual behavior vs. judging its correctness), explains why
accurately documenting a bug is actually the correct outcome rather than a
failure, and redirects the criticism to the actual source of the problem
(the code, not its documentation).