Maintenance, Handover and Revalidation

Shipping leaves a future maintenance problem: the next person or AI agent can see the artefact, but may not know which sources mattered, why a strange-looking choice was deliberate, what was deferred or how to check whether the result is still trustworthy. Without that context, every review starts as archaeology.

For durable work, leave a maintenance package that answers three questions:

What exists, and why does it look this way?
How should it be checked or updated?
What must be true before the review is complete?

The component parts have established names, though no single term covers the whole package. Maintenance handover and revalidation runbook is a useful composite label when one document carries all of them.

The component parts

Term	Job
Handover / knowledge-transfer document	Transfers enough context for another maintainer to continue safely.
Runbook / SOP	Gives repeatable instructions for operating or maintaining the artefact.
Maintenance	Updates the artefact after it ships.
Revalidation	Rechecks claims or requirements against evidence that may have changed.
Post-implementation review	The scheduled checkpoint after delivery.
Audit trail / provenance	Records where information came from and how changes were made.
Decision log / ADR	Records consequential choices, their context and rationale.
Change log	Records what changed between versions or reviews.
Acceptance criteria / Definition of Done	States the observable conditions for declaring the review complete.

A handover explains the system, while a runbook explains how to operate it. Provenance explains where claims came from, while the decision log explains why one option won. The change log records outcomes; acceptance criteria stop “reviewed” from meaning “looked at briefly”.

What goes in the document

Purpose and scope

Name the artefacts covered and the decisions this document owns. Link to the canonical files rather than copying volatile conclusions into the handover.

Current artefacts

List the source files, outputs, tests, reference material and deployment surfaces a reviewer needs. The list is a map; copying their content creates another source of truth.

Provenance and roles

Record which sources were primary, which notes were synthesis, which agents or people reviewed the work and who made the final judgement. “An AI reviewed it” is too vague if the model’s role was read-only advice rather than authority to edit.

Decision log

Record decisions that a future maintainer might otherwise “fix” back to an earlier, worse state. Each entry needs the choice and the reason; meeting-by-meeting narration adds little.

Revalidation runbook

Name the evidence surfaces and checks to repeat. For a technical system, that might include dependency releases, product documentation, security advisories, tests and live configuration. For an evidence-based reference, it might include guidelines, regulator material, product information and the sources that currently override an older review.

State the observation that separates pass from fail. “Check the links” is weaker than “every internal target resolves and every external URL returns the intended source”.

Refactor triggers

Refactoring changes structure without intentionally changing behaviour or meaning. Useful triggers include:

duplicated facts that are beginning to drift;
a summary and its detailed section disagreeing;
new components that no longer fit the existing grouping;
repeated caveats obscuring the actual recommendation; or
a document that has stopped working at its intended point of use.

A factual or behavioural change is maintenance, not merely refactoring. A known structural cost deliberately deferred is technical debt.

Acceptance criteria

The Definition of Done should be observable. A review might require:

every named evidence surface checked;
each changed claim linked to supporting evidence;
shared claims reconciled across their consumers;
tests, citations and links passing;
the decision/change log updated; and
the next review scheduled or explicitly judged unnecessary.

Review log and next trigger

Record the review date, outcome, material changes and reviewer. Then put the next review on a dated task surface. Writing “review in three months” inside the handover is documentation; scheduling the absolute date is the control.

A compact template

# [Artefact] maintenance handover and revalidation runbook

**Baseline:** YYYY-MM-DD
**Next review:** YYYY-MM-DD
**Scope:** [canonical artefacts]

## Purpose
## Current artefacts
## Provenance and roles
## Decision log
## Revalidation runbook
### Evidence/configuration update
### Reconciliation
### Mechanical checks
## Refactor triggers
## Acceptance criteria
## Review log

This is worth doing when the work is durable, high-consequence, assembled from mixed sources or exposed to fast-changing dependencies. A throwaway script or one-off draft rarely earns the maintenance surface.

Previous: Meta-Skills

Next: Glossary