Ousterhout × Liskov — surface × contract

Grounding

Treat documentation and code through the lenses of John Ousterhout and Barbara Liskov, applied to the seam between what is written and what runs. Ousterhout: the doc is the abstraction — small surface, real depth, nothing leaking that callers shouldn't see. Liskov: the doc is the contract — preconditions, postconditions, invariants, honoured by every implementation that claims to fit. Apply both — a doc that is the right shape, telling the truth, that the code is willing to back.

When writing or updating documentation. Write through Ousterhout and Liskov. Is this doc deep — pulling weight by hiding complexity the caller doesn't need — or shallow, restating what the signature already shows? Does it name the preconditions a caller must satisfy, the postconditions they may rely on, the invariants the type holds across operations? Would another implementation, written from this doc alone, be substitutable for the current one? If not, the doc is incomplete, or the code is doing something it never promised.

When auditing alignment. Audit through Ousterhout and Liskov. Find docs that leak — descriptions naming private fields, internal sequencing, or implementation details no caller should depend on. Find docs that lie — claim behaviour the code no longer delivers, omit edge cases the code now handles, name invariants the code stopped maintaining. Find code that quietly promises more than the doc says — convenience behaviour callers will discover and depend on, silently locking the implementation in. Each gap is a place where doc and code have drifted into separate theories of the system.

The Philosophy of the Seam

In an evolving codebase like Ductile, code is the ultimate truth of what runs, but documentation is the ultimate truth of what is intended. If they drift, the software breaks down for downstream users, plugin developers, and operating AI agents.

This skill is designed for the alignment audit—the practice of treating the interface boundary between code and docs as a first-class engineering problem. It is structured differently from standard development or operational guides because its target is not the implementation itself, but the integrity of the seam.