A contract, not a prompt

Your team inherits a "meal practicality checker" as a Notion doc: two pages of instructions, a few-shot block, and a note saying "use GPT-4." Code review cannot ask whether the interface is complete. QA cannot tell what "done" means. When the household rejects Tuesday's plan, nobody knows whether the failure is specification, model, or missing context, because there is no specification, only prose meant to coax a model.

A cognitive unit closes that gap. The prompt is one implementation detail inside the contract, not a substitute for it. Contracts are how senior engineers review intelligent features the same way they review APIs: completeness, edge cases, authority limits, and test hooks, before anyone tunes adjectives.

Helpful context: What is a cognitive unit defines the artifact. Making the specification executable extends the same discipline to whole systems. The model is not the system warns against stopping at substrate choice.

Side by side

Concern	Prompt doc	Contract
Decision owned	Implied in instructions	One sentence: decides
Inputs	Examples in prose	Declared fields with types
Thin grounds	"Use best judgment"	Abstain and refer branches
Review	Taste in wording	Interface completeness
Evidence	None	Suite bound to identity
Substitution	Find-replace across repos	Swap behind stable name
Authority	Unstated	Explicit grants and refusal

Code reviewers know what to look for in a contract. They cannot perform the same work on a prompt alone, because a prompt has no obligation to declare what it will not do.

Prompt docs feel faster on day one. They match how vendors ship "starter templates." Contracts feel like paperwork until the first production incident, the first model swap, or the first request to reuse AssessMealPracticality in a second product. Then the contract is what lets you substitute, measure, and assign ownership without rereading every feature. The resistance often hides a deeper issue: the team has not yet stated the open decision clearly enough to declare. "Declare the contract before any prompt is written" is therefore a clarity test. If you cannot write decides, the decision is not yet clear enough to delegate.

What this looks like in practice

Prompt-only ComposeWeek: "You are a helpful meal planner. Given the week below, create a balanced plan.."

Contract ComposeWeek:

inputs: interpreted_week, hard_constraints, candidates
decides: Coherent provisional weekly plan under constraints
returns: plan_version | abstain | refer
postcondition: every evening has zero or one assigned meal
level: composite (may call GenerateCandidates, AssessMealPracticality)
check: suite://meal/compose-week@v3

The prompt text lives in the identity ring, versioned with the decision. Callers depend on the contract, not on whether paragraph three mentions spinach. Reviewers can ask whether postconditions are enforceable. Evaluators can bind cases to the decision sentence.

Prompt docs often smuggle context as narrative: "here is everything we know about the household." Contracts declare inputs, which fields are required, which memory grants apply, what happens when a field is missing. That shift is what makes abstention possible. A contract can say: if evening_context.busy_flags is absent, return abstain with missing: ["evening_context.busy_flags"]. A prompt doc typically guesses. For invoice intake, the same discipline applies: AssessExplanationCredibility declares which purchase order version, delivery note, and variance fields it requires, not "use all attached PDFs."

The review meeting test makes the difference concrete. Imagine a code review where someone submits only a prompt doc. The reviewer can ask whether the tone is professional. The reviewer can suggest fewer adjectives. The reviewer cannot ask whether abstention is defined when the calendar is missing. The reviewer cannot ask which suite will catch regression when the model vendor updates safety filters. The reviewer cannot ask who owns the decision when the household disputes Tuesday's busy flag. Now imagine the same review with a contract diff. The reviewer sees new inputs, a changed decides sentence, an added refer branch, a purity level bump from sealed to reading. The conversation is about interface completeness, the same conversation senior engineers already know how to have. That shift is why Thoughtware treats contracts as first-class artifacts. Prompt tuning without a contract is craft. Contract-first development is engineering.

What the contract buys

Making the specification executable extends this discipline to whole systems: agents, libraries, memory grants, and deterministic gates appear in one reviewable artifact. cognitive unit contracts are the cells of that spreadsheet. A system spec that lists assistants without listing cognitive unit edges is still a feature deck, not an architecture. For the Meal Companion, an executable fragment might read: "Before compose, every busy evening must have at least one candidate assessed by AssessMealPracticality or an explicit abstention recorded." That sentence is testable. "Be helpful about busy nights" is not.

When GPT-5 or the next vendor release arrives, prompt docs panic. Contracts calm. Callers still depend on AssessMealPracticality returning fit, abstain, or refer with grounds. Maintainers update identity, template and decision wording, and remeasure. Policy may shift default models. Environment may change log sinks. The contract tells you which of those events requires a warranty update. Teams that skip contracts discover this during the first substitution request: "We just need the same behaviour in the mobile app." Without a contract, same behaviour means copying prose and hoping. With a contract, same behaviour means invoking the same name from the domain library.

Contract (review first)	Template (identity ring)
decides sentence	Wording that implements the decision
Input and output types	Few-shot examples
Abstain / refer shapes	Tone and formatting preferences
Purity level	Chain-of-thought style (if any)
Suite pointer	Model-specific phrasing

Confusing the two is how teams end up code-reviewing adjectives while leaving authority undefined.

Authority and thin grounds

Contracts can declare pre-conditions, what must be true before the call is valid, and post-conditions, what must be true of a successful answer. ComposeWeek might post-condition: every evening has zero or one assigned meal. Deterministic code can verify post-conditions even when judgment content varies. Pre-conditions shrink unbounded domain: do not call AssessMealPracticality without evening_context and candidate_meal. The cognitive unit abstains if they are missing. Deterministic code may reject the call earlier if the schema is malformed.

Prompt docs hide failure modes in footnotes. Contracts surface them as typed returns, and reviewers see abstention and referral branches in the same diff as inputs and outputs. That visibility is how teams discover missing authority before launch rather than after the first medical-diet request. Refer branches name who must decide and why the cognitive unit cannot. Abstain branches name what is missing. Both are first-class, not HTTP 500 with a friendly message.

Model vendors ship prompt templates because templates sell subscriptions. The contract is what makes the judgment portable across vendors, measurable across versions, substitutable across products. Copy vendor wording into the identity ring if useful, but never confuse the vendor starter kit with the architectural artifact.

Declare the contract before any prompt is written. If you cannot, the decision is not yet clear enough to delegate.

The cognitive unit · Ch. 2

Contracts in daily work

Prompt docs live in Notion and drift. Contracts live beside code and diff. The review question for a contract PR is: "Is the interface complete for the decision claimed?" The review question for a prompt PR is: "Does this sound better?" Teams that conflate the two optimise prose while leaving authority undefined. Requiring contract fields in the same pull request as template changes when identity moves, and suite updates when behaviour claims change, prevents that conflation.

Template review asks: "Will the model behave?" Contract review asks: "Is the delegation complete?" Both matter, but only the second is possible before implementation exists. Teams that skip contract review optimise for demo fluency, then wonder why production lacks abstention branches.

For invoice intake, ExtractInvoiceFields as a Skill composes many steps. AssessExplanationCredibility as a cognitive unit owns one judgment inside it. Contracts belong at the cognitive unit boundary even when Skills orchestrate the procedure. Scaffolding new cognitive units from a contract template in the repo, empty decides, abstain/refer stubs, suite pointer placeholder, before any template prose forces the PR conversation toward interface completeness. The contract is the artifact you hand to security, compliance, and the engineer who joins in six months. The prompt is the artifact you hand to the model. Both survive, and reviewing the right one in the right meeting is how teams ship judgment they can govern.

What to do next

Every new cognitive unit starts from the contract scaffold, not from vendor prompt paste. The decides sentence comes before the template body. Required working-state fields appear as typed inputs, not narrative context dumps. Abstain, refer, and postconditions declare before wording tunes. A suite pointer attaches in the same change as the identity version.

See grounds are part of the answer and three rings of a cognitive unit.

Read next: Grounds are part of the answer.