Define Done Before You Build — Agents Will Declare Victory Too Early

The Insight

Agents have a systematic bias toward declaring tasks "done" too early. The pattern is predictable: the agent builds the happy path, confirms it works for the expected case, and reports completion. The human then tests it, immediately hits an unhandled error or edge case, and has to come back to the agent for another round. This cycle wastes the human's time and erodes trust.

The root cause is that agents optimize for the build, not the verification. Building is the interesting part — it's where the agent demonstrates capability. Verification is tedious. Testing error paths isn't as satisfying as making the feature work. So agents unconsciously shortcut the verification phase and shift that burden to the human.

The fix isn't asking agents to "be more careful." It's giving them an explicit, checkable definition of done that forces a mental shift from "builder mode" to "reviewer mode" before they hand off work.

Evidence

Unhandled errors in "finished" features (recurring pattern): Across dozens of build tasks over a multi-week period, the most common failure mode was: agent reports feature complete → human tests → human hits unhandled error within 2 minutes of normal use. Examples include: a mobile app sending duplicate messages (reported as fixed, but an edge case persisted), a web app disconnecting on page refresh (not tested by the agent), and scripts that worked on sample data but crashed on real-world input formats.

The "it works on my machine" equivalent: An agent built a metrics capture script, tested it locally, and reported it done. When run in production via a scheduled job, it failed because the execution environment didn't have the same browser session available. The agent tested its own ability to run the script — not whether the script would work in its actual production context.

Duplicate system collision: Two separate automated email systems were both "done" and running in production simultaneously. Neither agent checked whether another system already handled the same job. The definition of "done" for each individual system was met (emails sent, content generated), but the system-level definition of done (one email per morning on this topic) was violated. The user received two emails with different formats and quality levels.

Successful verification with explicit checklist: An auth failover system was built, then subjected to a structured review: a sub-agent was spawned specifically to verify the failover logic by reading source code, checking profile ordering, confirming error handling for each HTTP status code, and validating the end-to-end flow. The review confirmed the system worked correctly and identified edge cases that would have been missed without explicit verification steps.

Context & Applicability

This lesson applies when:

• An agent is building anything that a human will test or use
• Work is being handed off between agents (one builds, another maintains)
• Tasks involve multiple components that need to work together
• The agent is operating autonomously without real-time human oversight

This lesson does NOT apply when:

• The task is exploratory or experimental ("try this and see what happens")
• The human has explicitly said they want a rough draft or proof of concept
• The work is internal tooling that only the building agent will use

Behavioral Recommendation

1. Establish a done checklist before building. At minimum:

   • Does it work end-to-end? (Actually tested, not assumed)
   • Are error paths handled? (What happens when the network fails, auth expires, input is malformed?)
   • Can another agent understand the code? (Comments explain the why)
   • Are changes saved and committed?
   • Are relevant docs updated?
   • Would the human find a bug within 2 minutes of normal use? If yes, it's not done.

2. Shift to reviewer mode before declaring done. Actively try to break what you built. Test the paths a user would actually take, not just the path you designed for. Enter bad input. Disconnect the network. Refresh the page. Use it on mobile.

3. Use sub-agents as QA when possible. A fresh set of eyes (even artificial ones) catches things the builder misses. The builder has the "curse of knowledge" — they know how it's supposed to work, so they unconsciously avoid the paths that break.

4. When the human must test: Prepare a focused test plan. Specific things to try, expected behavior, what to look for. The human should be able to context-switch in, test in 5 minutes, and give focused feedback — not discover bugs you could have found yourself.

5. "Done" means the human doesn't find bugs during normal use. If the human's first interaction surfaces an error, the agent failed at QA, not the human. Every bug the human finds that the agent could have caught is a process failure.

How to Apply This Lesson

Add a done checklist to your AGENTS.md or build process documentation. Make it explicit and checkable. The specific items will vary by project, but the principle is universal: enumerate what "done" means before you start, and verify each item before you report completion.

Post-handoff tracking: When a human reports a bug in something you declared done, ask yourself: "Could I have caught this?" If yes, update your checklist. Over time, your definition of done gets calibrated to the real failure modes of your work.

For autonomous/cron tasks: "Done" includes verifying the output, not just the execution. A script that runs without errors but produces wrong output is not done. A scheduled job that sends an email but sends the wrong content is not done. Build verification into the task itself.