contract-review

name

contract_review

description

Adversarially verify an implementation against its declared contracts — docstrings, specs, ADRs, type signatures, commit messages, and error-classification tables — catching both broken promises and behavior no contract mentions. Use when the user asks to "review against the spec", "check the contract", asks "does the code still match the docstring/ADR", wants a commit set checked for documentation drift, or after landing a change that touches documented behavior.

Contract review — the code vs. its promises

A procedure for reviewing a commit set through one lens: every behavior is governed by a written promise, and when code and promise disagree, exactly one side is wrong. The output is a findings list where each finding names the wrong side — code or contract — with a quote from both.

Scope

The unit of review is a commit set — one commit or a contiguous range — or an explicitly named code area. The review surface is the diff of that set; judgment reads the full files at the tip commit. When invoked standalone with no scope handed in, resolve it before reading any code: default to the latest commit, widen to the whole landing when the tip commits are one change split into pieces, and state the resolved SHAs in the report. "The diff" below always means this resolved surface. Commit messages are contract material: each scoped commit's message enters the register in step 1 — its claims ("ran red on real MSSQL", "X is deleted", "all legs pass") are promises to verify like any docstring.

The core insight: most review defects hide in the gap between what the code does and what something says it does. Prose that lies about correct code is still a defect — stale documentation measurably breeds future bugs, because the next editor trusts the words. In this repo the default arbitration is written down: code is a build artifact of context/; when they disagree, fix the code unless the context is demonstrably wrong.

Process

1. Inventory every contract governing the touched code

Before reading any implementation, collect the promises. For each touched module/function, gather:

• Docstrings — module and function, including docstrings of callers that describe what the touched code will do for them.
• Type signatures — parameter and return types, Good | Error unions, None-ability, declared exceptions. A signature is a contract the type checker only partially enforces; read what it claims.
• Specs and ADRs — the open spec in context/specs/ the branch serves, plus any ADR in context/decisions/ naming this behavior.
• Error-classification tables and invariants — error taxonomies, frozensets of accepted values, and repo-wide invariants from CLAUDE.md (e.g. no statement grows unboundedly with batch size; 10,000+ file batches are a supported contract).

Build a contract register: source (file:line), the promise in its own words, and the code it governs. Touched public behavior with no findable contract is itself a finding — an undocumented boundary.

2. Read contract-first, predict, then verify

Take an adversarial stance borrowed from perspective-based reading: read the contract before the code and write down what the code must therefore do — inputs it must reject, outputs it must produce, errors it must classify. Only then read the implementation and check the predictions. Reading code first invites rationalizing whatever it does; reading the promise first makes every deviation jump out.

3. Compare in both directions

Direction A — broken promises. For each register entry, locate the code that delivers it. A promise with no delivering code, or code that contradicts it, is a defect. Check the caller's side too: does the code demand preconditions the contract never imposed on callers?

Direction B — silent contract growth. Re-read the diff asking what the code now does that no contract mentions: new parameters, new error paths, new side effects, changed ordering, widened accepted input, behavior on inputs the old code rejected. Undeclared behavior is not free bonus — it is a contract nobody agreed to, which callers will depend on and nobody will preserve. Every such behavior gets a finding: either the contract must grow to cover it, or the behavior must go.

4. Audit docstring and comment honesty

Prose that lies about what the code does is a defect even when the code is correct. Hunt the classic decay signatures:

• Parameter or field names in prose that no longer exist in the signature.
• "Always"/"never"/"only" claims falsified by a branch added in this diff.
• Examples in docstrings that would no longer run or return what they show.
• Comments explaining a why that the diff just invalidated.

The fix for a lying comment is usually to fix the comment — but first ask whether the prose records the intended behavior and the code drifted. Intent decides which side is wrong, not recency.

Boundary with ownership review. This lens judges whether the prose is true, not whether the implementation sits in the right module. A promise that is honoured, but honoured in every caller rather than where it is declared, is a placement defect owned by ownership_review — leave it there rather than filing it twice.

5. Probe contract completeness at boundaries

Where the contract is silent, the code is deciding policy in the dark. At every touched public boundary ask:

• Errors — is every failure mode classified? Does each raised or returned error appear in the declared taxonomy, and does prose say which failures are lawful answers (None) vs loud violations?
• Edges — empty input, duplicate keys, a 10,000-item batch, ordering of results, partial-failure behavior mid-batch, concurrent callers. If the code has an answer the contract doesn't state, file a contract-gap finding: the answer exists, it just isn't promised.

6. Hold the evidence standard

Every finding must quote both sides of the disagreement: the exact contract line and the exact code line, each with a file:line reference. A paraphrase is not evidence. If you cannot produce both quotes, it is a hunch, not a contract finding — either dig until you can, or drop it. Verify quotes by re-reading the cited lines before reporting; a review that misquotes a contract is itself lying prose.

7. Deliver the findings

Report a findings list, most severe first. Each finding states:

• Severity — breach (code violates a declared promise), growth (undeclared behavior at a boundary), decay (prose lies about correct code), gap (contract silent where the code decides).
• Which side is wrong — code or contract — and why, arguing from intent: what was the promise for, and which artifact still serves it. Default when intent is unrecoverable: the contract wins.
• The two quotes with file:line for each.
• Fix direction in one line (change the code / change the prose / extend the contract), without writing the fix.

Close with the boundaries checked and found clean — a contract review that reports only findings hides how much of the surface was verified.