contract-derivation

Contract Derivation

Take a design document and produce a set of per-module contracts (manifests) that are complete in isolation. Each manifest must let an implementor build its module correctly without seeing any other part of the system.

Why this skill exists

A design document captures the system's structure, but its module contracts often lean on shared context — adjacent modules, the system's purpose, implicit assumptions a human reader would fill in. Compartmentalised implementation cannot rely on any of that. The implementor of one module sees only the manifest for that module, and nothing else. Anything the manifest fails to state will either be guessed (badly) or surfaced as a re-raise.

This skill's job is to take each module's contract from the design doc and harden it: make every implicit assumption explicit, name every behavioural guarantee, define every error mode, and lock down every data shape it references. The resulting manifests are the durable source of truth for the rest of the build.

Process

1. Read the design doc end to end first, and read the structural tier

Before deriving any single manifest, read the entire design doc. Each manifest will be produced in isolation, but you cannot produce them in isolation — you need the whole picture to know which assumptions are shared, which data shapes flow where, and which modules depend on which.

The design doc's "Structural tier" section shapes everything you do:

• single_module: Produce one manifest. No vocabulary file is produced by default — the single module's contract names its own types inline. If you do produce a vocabulary file (only when the brief specifically names types as part of an external interface), every entry MUST be sharing: local; no sharing: shared entries are valid for single-module projects. No composition tree. See step 3 for the strict rule.
• small_multi_module: Produce 2–4 manifests plus one vocabulary file. Step 3 (catalogue shared vocabulary) runs as written. The composition layer above will be a single composition; sharing markers matter for the types that flow across the module boundary.
• full_decomposition: Produce 5+ manifests plus a full vocabulary. All steps run as written. Sharing markers are critical because the composition tree is deep.