27 Finish with evidence

A change can be implemented, tested locally, reviewed, integrated, and still not accepted for its intended use. These are distinct states because they answer distinct questions. Treating them all as “done” forces the next person to reconstruct what actually happened.

Completion should be a bounded claim about a particular result. It identifies what was requested, what revision carries the result, which observations support it, and which obligations remain. This is neither a victory speech nor an archive of every command. It is the account someone needs to decide what they can safely rely on next.

The resource example gives us a concrete target. The change is complete for its agreed scope when the selected replacement can be used after publication, failed preparation preserves the working version, and the required evidence supports that behavior in the named environment. A future desire for another source provider does not automatically keep this change open. A required publication check that never ran does.

Bind the claim to the candidate

A passing result belongs to the revision and environment exercised. Subsequent source changes may invalidate it. A documentation-only successor can sometimes preserve the relevant implementation evidence, but that relationship should be justified rather than assumed. A report copied from an earlier branch is historical evidence, not a fresh run.

The inspected Coding-Standards history provides an uncomfortable and useful example. At main revision dcc56f26, the exact-head hosted Engine job reported 613 tests with one failure. The failing proposal-analysis test received AUTHORING.INVALID_SEMANTIC_REVISION; the later complete verification command was not reached because the shell stopped on failure. Passing earlier groups did not make the whole gate pass. Observed hosted job, workflow sequence.

Source inspection showed a fixture hardcoding accepted revision one for a policy whose current declaration was revision two. That strongly supports a stale-fixture diagnosis. It does not show that a repair was applied or that the intended projection-count assertion passed afterward. The book's research made no repair and performed no rerun. Fixture, current declaration.

The distinction is practical. “The failure appears to be an obsolete fixture” tells a maintainer what to investigate. “Verification passed” would tell them something the evidence does not establish. A persuasive diagnosis cannot stand in for the missing observation.

Write an account someone can use

For the illustrative application, a release account awaiting a required hosted check might read:

Result: Candidate R1 implements replacement through the supported local consumer. Preparation failures preserve the old active version. No additional source provider or runtime installation is included.

Local evidence: The recorded checks cover opening the old version before publication, rejecting an invalid candidate, opening the requested replacement after publication, and cancellation while checking is held. The record names the commands, environment, and candidate R1.

Review: The lifecycle reviewer inspected R0 and found premature completion. The repair produced R1; the reviewer rechecked the finding on R1, and the local checks above exercised R1. Any later source change requires assessment of which evidence remains applicable.

Integration: R1 is on the agreed integration branch. The required hosted verification of R1 has failed, so release acceptance remains blocked.

Next obligation: Investigate the failing hosted check, repair within the agreed scope, and obtain the missing result. The release owner makes the acceptance decision after that evidence is available.

This is a specimen of wording, not a report of tests performed on a real application. It demonstrates that substantial useful work can be complete while a specific release obligation remains open. The account gives the next worker a concrete continuation rather than either an exaggerated success or a vague “not done.”

When all required checks pass, the account can become shorter. State the delivered behavior, revision, verification, material limits, and destination. Do not make the user navigate a long ledger to find the answer to whether they can use the result.

Keep unknowns distinct from defects

An untested platform is not automatically a known failure. A failed required check is not merely an untested platform. A known defect accepted for a bounded release is different from either, and should name who accepted the consequence and under what conditions.

This distinction prevents both overclaiming and needless paralysis. If the agreed release supports one local platform, absence of qualification elsewhere can be an explicit limit. If cross-platform behavior is part of the promise, the same absence is a blocker. Acceptance follows the intended scope rather than a universal checklist.

Do not hide unresolved incidents behind nearby successful repairs. A source defect may have been corrected without reproducing the original report. Preserve the distinction until the evidence connects them. Likewise, an operator's decision to retire an uncertain task does not rewrite its historical outcome into confirmed success.

Finish the operational edges

Delivery includes the artifacts someone needs to use or continue the work: the actual patch or release, the relevant documentation, and retrievable evidence. Temporary branches and environments should receive a justified disposition. Cleanup must preserve uniquely held work and any evidence required for recovery or maintenance.

Remaining tasks should have a purpose and an owner. “Improve everything later” is not a useful obligation. “Qualify the same publication behavior on the second supported platform before enabling it there” is. If a required external process is still running, completion reporting should reflect that and the responsible person should continue following it to a result.

There is also a stopping rule. Once the requested outcome is accepted and its operational obligations are resolved, unrelated architectural ambitions belong to another decision. A rigorous process should make completion easier to recognize, not place it beyond reach.

Audit the word done

Take a recently completed change and try to reconstruct its claim from the final report alone. Can you identify the exact candidate, the behavior delivered, the checks that ran, the checks that failed or did not run, the review scope, and the acceptance decision?

Rewrite the account so another person can distinguish evidence from diagnosis and current status from historical success. The observable outcome is a reader who knows what they may rely on and what, if anything, still needs action. That is a useful end to a change and a trustworthy beginning for the next one.