Chapter 40 - Definition Of Done For AI-Assisted Work

Part: VIII - The Field Manual

Thesis

Done is not a feeling. It is a state the system can verify. For AI-assisted work, done means the change is built, verified, documented, understood, and recoverable — in that order. For AI-native work, done is a property of the whole proposal-to-commit system, not just the code that implements it: a capability is not done until there is evidence that a wrong proposal cannot silently cross its commit boundary.

Key Line

Done means owned, tested, understood, and recoverable. Not just passing.

Why “Tests Pass” Is Not Done

The test suite passing is necessary. It is not sufficient.

A test suite that tests the wrong thing passes on wrong code. Documentation that describes the old behavior passes no test but misleads the next person. A change no one can explain may be correct — but it cannot be maintained or debugged when it is not.

“Done” in AI-assisted development requires more than green CI because the failure modes of AI generation go beyond the failure modes of human coding. Plausible-but-wrong output (Ch 31) passes review. Tests that test the wrong thing (Ch 15) pass CI. Documentation drafted by a model may be accurate for the code as of one hour ago and incorrect for the code as it exists now.

Done requires a standard that covers all of these.

The Five Conditions

1. Built

The code builds without errors. All imports resolve. The type check passes. No syntax errors, no unresolved references, no compilation failures.

This is the floor. If the code does not build, nothing else matters.

2. Tested

The new behavior is covered by tests that would fail without it.

Two parts to this condition. First: tests exist for the new behavior. Second: those tests would fail against an empty or incorrect implementation — they are not tautologies (Ch 15).

Negative cases are tested where they matter: validation logic, authentication, data processing, error handling. The test that only covers the happy path is a partial test.

If the change fixes a bug, a regression test is committed alongside the fix. The regression test fails on the unfixed code and passes on the fixed code.

3. Documented

Any change that affects a public interface, a CLI command, a configuration option, or a developer-facing behavior has updated documentation.

The documentation reflects the current behavior, not the behavior as of the previous version. Setup instructions have been run. API examples have been executed. Default values have been verified against the running code.

If the model drafted the documentation, the documentation has been verified by a human against the actual current behavior.

4. Understood

The person committing the change can explain: what it does, why it is structured the way it is, and what would happen if the change were reverted.

This is the ownership requirement. A change that is committed without being understood is committed with an ownership gap (Ch 30). The ownership gap compounds: the next person builds on code they do not understand either.

“I ran the tests and they pass” is not understanding. Understanding is: “This function does X because Y, and the test at line 42 would catch it if that changed.”

If the change cannot be explained, it is not done. Ask the model to explain it. Verify the explanation against the code. If the explanation and the code diverge, the change needs more review.

5. Recoverable

If this change causes a problem, there is a path to undo it.

For code changes on a branch: the rollback is a git revert or a branch deletion. The path exists.

For database migrations: the migration is reversible. The down migration has been tested.

For deployments: the rollback procedure is documented. The previous version is tagged. The procedure has been tested — at minimum, in staging.

For feature flags: the flag can be turned off without a deploy. The state of the system with the flag off is understood.

A change that cannot be undone is not done. It is a commitment with no exit.

The Observable Markers Condition

For sessions that used the Observable Markers pattern (Ch 38): the markers have been removed.

No VCB-MARKER comment remains in the committed code. No test borders, no overlay labels, no prototype console logs. The markers served their purpose during the Validate stage. They must not cross the commit boundary.

Done includes: the sweep was run, the sweep was verified, the clean version was reviewed.

The Handoff Condition

If the session is ending — whether or not the work is complete — the handoff file has been written and committed.

If the work is complete: the handoff documents what was built and what comes next.

If the work is not complete: the handoff documents what was done, what remains, why it was stopped here, and the next step.

The session can end without the work being done. The session cannot end without the handoff being written.

The Definition Of Done Checklist

Apply this before any commit that claims a unit of work is complete.

Built
- [ ] Code builds without errors
- [ ] Type check passes with no new errors
- [ ] No unresolved imports or references

Tested
- [ ] New behavior is covered by tests
- [ ] Those tests fail without the change
- [ ] Negative cases are tested where relevant
- [ ] Bug fixes include a regression test

Documented
- [ ] Public interface changes are reflected in docs
- [ ] Setup instructions verified by running them
- [ ] Model-drafted docs verified against current behavior

Understood
- [ ] I can explain what this code does
- [ ] I can explain why it is structured this way
- [ ] I can explain what would happen if it were reverted

Recoverable
- [ ] Rollback path is identified
- [ ] For migrations: down migration is tested
- [ ] For deploys: rollback procedure is documented

Clean
- [ ] Observable markers removed and sweep verified
- [ ] No secrets or credentials in the diff
- [ ] Handoff file written and committed

The Runtime Definition Of Done

The five conditions above answer “is this code done.” A capability that puts a model in the runtime loop needs a parallel answer to a different question: “is this capable of running safely, on every request, without a human reading each one.”

Runtime done has its own five conditions, and none of them is satisfied by the build-time five, even when the build-time five are fully met.

1. Happy path validated. The capability does what it is meant to do when the proposal is well-formed, authorized, and legal. This is necessary. It is the smallest part of runtime done.

2. Rejected paths validated. Every validator - schema, authorization, domain rule - has been exercised with a proposal specifically designed to fail it, and the rejection behaves as designed: the right error, the right trace record, no partial effect left behind.

3. Permission failures validated. An unauthorized caller attempting the action is tested explicitly, not assumed to be blocked because the authorization check exists. The difference between “the code contains an authorization check” and “the authorization check was exercised and confirmed to reject” is the difference between hoping and knowing.

4. State recovery and rollback validated. If this capability writes state, executes an action, or publishes a claim, there is a tested path to undo or compensate for a wrong instance of it - Chapter 17’s compensating-action pattern, exercised, not just designed.

5. Observability in place. Every proposal this capability makes - accepted or rejected - is traced somewhere a person would actually look, and there is a named way to notice if the escape rate for this capability changes.

Runtime done also inherits the build-time conditions where they apply: the capability is documented (source of truth, allowed proposals, and commit boundary recorded, not just the API), and it is understood (whoever is granting the capability can explain what the model can now cause, not just what code was written).

The Silent-Crossing Test

Before calling a runtime capability done, produce actual evidence for one specific claim: a wrong proposal cannot silently cross this capability’s commit boundary.

“Silently” is the operative word. A wrong proposal that gets rejected loudly - a clear error, a trace record, a visible failure - has not violated this test even though something went wrong. The test fails when a wrong proposal succeeds: writes bad state, executes an unauthorized action, publishes an unsupported claim, and nothing in the system flags it as different from a correct one.

The evidence is not “the validator exists.” It is a demonstration: a deliberately malformed, deliberately unauthorized, or deliberately illegal proposal was sent through the capability’s real path, and the system’s behavior on that attempt - rejection, trace record, no silent effect - was observed and confirmed, not assumed from reading the code.

A capability that has never been tested this way is not done. It has been built and hoped about.

Provisional Done

Not every unit of work can satisfy all five conditions before it must move.

In a prototype or spike: tests may be deferred. The decision to defer must be documented: which conditions were deferred, why, and what the plan is to satisfy them before the code goes to production.

Provisional done is explicit. It is not “we’ll get to it later.” It is: “tests are deferred, documented in issue #87, must be closed before merge to main.”

Undocumented deferrals are not provisional done. They are ownership gaps with a green CI indicator.

Closing The Loop

The definition of done is the final gate in the Propose — Validate — Commit loop (Ch 13).

The loop started with a proposal. The proposal was validated by controls, review, and the markers pattern. The definition of done is the structured check that the validation was complete before the commit crosses the boundary.

Done is not what the model declares. Done is what the system, the tests, and the reviewer confirm.

Practical Artifact — Definition Of Done Card

Post this where the team can see it. Review it before every commit.

Condition	Check	Done when
Built	Build and type check pass	No errors, no unresolved references
Tested	Tests cover new behavior, fail without it	Green and meaningful, not just green
Documented	Docs match current behavior	Verified by running, not by reading
Understood	Can explain what, why, and what-if-reverted	Not just “the tests pass”
Recoverable	Rollback path exists and is documented	Tested in staging for deploys
Clean	Markers removed, no secrets, handoff written	Sweep verified before merge

Export

Copy this block into your CLAUDE.md, agent instructions, or project checklist.

Done means owned, tested, understood, and recoverable. Not just passing.

vcb_chapter: 40
title: "Definition Of Done For AI-Assisted Work"
key_line: "Done means owned, tested, understood, and recoverable. Not just passing."
thesis: "Done is a verifiable state, not a feeling. For AI-assisted work it requires five conditions: built, tested, documented, understood, and recoverable."
checklist:
  - item: "Code builds and type check passes"
    protects: "against syntax errors and broken imports reaching committed code"
  - item: "New behavior is covered by tests that fail without the change"
    protects: "against green CI that does not verify the actual new behavior"
  - item: "Docs verified against current behavior, not drafted and accepted"
    protects: "against AI-generated documentation that describes old or incorrect behavior"
  - item: "Reviewer can explain what the code does and why"
    protects: "against ownership gaps that make future bugs unmaintainable"
  - item: "Rollback path is documented and tested"
    protects: "against unrecoverable deployments and irreversible state changes"
  - item: "Observable markers swept and handoff file committed"
    protects: "against prototype artifacts in production and context loss between sessions"

Code builds, type check passes — protects against broken imports in committed code
Tests cover new behavior AND fail without it — protects against meaningless green CI
Negative cases tested where relevant — protects against happy-path-only coverage
Bug fixes include regression test — protects against recurrence of fixed bugs
Docs verified by running, not by reading — protects against stale AI-drafted documentation
Can explain what it does, why, and what-if-reverted — protects against unowned commits
Rollback path documented and tested — protects against unrecoverable deployments
Observable markers swept — protects against prototype markers in production
Handoff file committed — protects against context loss at session end