Cognitive Units

Software already knows how to package computation. A function has a name, typed inputs, a return shape, and tests. Thoughtware asks for the same discipline around judgment: a named edge you can call, measure, share, and improve without reopening the whole system.

In the Weekly Meal Companion, deciding whether a traybake fits a busy Tuesday is interpretive work under household constraints, competing goals, partial information, reasonable disagreement at the margin, not arithmetic. That work gets a name, AssessMealPracticality, and a contract callers can invoke without reading the template. The contract is the product. The template is one implementation detail inside it.

Helpful context: What is judgment defines the load-bearing term. Two questions that sort a decision explains open versus closed work. Where does a decision live? asks where this contract sits in the stack. This page is the canonical definition. Other notes apply it and link back here.

One bounded judgment

A cognitive unit owns one open decision. Compounds that classify, compare, assess, and draft are several judgments glued together, and splitting until the edge matches the judgment is how you preserve measurable, priceable, substitutable edges. The full rule lives in one cognitive unit, one open decision.

If the cognitive unit name contains "and," suspect a compound. GenerateAndCritiquePlan is two cognitive units and some orchestration, not one primitive. The compound pattern hides cost, hides failure, and forces every caller to accept a bundle they may not need. Architecture review treats "and" in a name as a smell until proven otherwise.

The decision must be wrong-answerable: competent reviewers can disagree or get wrong answers on marginal cases. Closed arithmetic wrapped in a cognitive unit is not an open decision, it is an expensive way to perform code. By the same token, a cognitive unit is not a prompt file, a model, an agent, a Skill, a feature, a chat session, or a chain. Several model calls under one name are several cognitive units plus code. See what is not a cognitive unit for the full negation list.

Purity is five capabilities, not a virtue: evaluate in isolation, cache, re-run, know cost, and replay. cognitive units declare a level from sealed through acting. Each impurity trades predictability for reach. Acting writes belong outside the cognitive unit edge, in deterministic code. The full ladder is purity and the five levels.

Three rings

Everything a cognitive unit can carry belongs to one of three rings: identity (name, decision, template body), policy (model defaults, sampling, cache, suite pointer, overridable at the call site), and environment (logging, stores, process budget, outside the declaration).

Knowing which ring a change belongs to settles most versioning arguments. Swap the default model? Policy. Rewrite the decision sentence? Identity. Route logs to a new sink? Environment. Three fields are required in a declaration: name, decides, and body. The rest are optional with defaults, and nothing from the environment ring appears in the declaration by design. See three rings of a cognitive unit for the full treatment.

Answer, abstain, refer

A useful cognitive unit does not invent grounds when the case is thin. Answer, abstain, and refer are legitimate structured results, not failures to minimise.

Abstention reports that the cognitive unit lacks enough information to decide. Referral reports that the decision belongs to someone with authority the cognitive unit does not have. Both are findings about the case. They enable callers to fetch, escalate, or branch, unlike a confidence score that collapses distinct remedies into one number. A cognitive unit that cannot abstain will fill gaps with fluent invention, and that is among the quietest failure modes in intelligent systems. Read more in abstention as a result.

What this looks like in practice

Walk one cognitive unit end-to-end: JudgeWeekdayPracticality, a judge-library entry in the Meal Companion.

Inputs: the provisional weekly plan, interpreted calendar, endorsed household knowledge (busy evenings stay under twenty-five minutes of active effort). Judgment: assess practical fit across the schedule, not whether individual meals are good in isolation. Returns: structured findings with severity, plus checkable grounds citing which evenings violate which constraints, or abstain if the week representation is incomplete. Does not: compose the plan, purchase groceries, or override allergy rules. Those live in other cognitive units or in code.

Deterministic code validates schemas and enforces allergies before and after the call. The agent strategy decides when to invoke the judge. The cognitive unit answers one question and stops. Contrast that with the unnamed alternative: one prompt that interprets, generates, checks allergies in prose, judges Tuesday, and drafts a shopping list. Failure anywhere rewrites everything. No suite attaches to weekday practicality because it was never named.

The declaration below shows what a full contract can carry. No real cognitive unit needs every field on day one, but the shape matters for review.

cu AssessMealPracticality

 inputs candidate_meal, evening_context

 decides Whether this candidate fits this evening's
 practical constraints

 returns fit: { verdict, reasons[] }
 | abstain: { missing: [text] }
 | refer: { to: role, why: text }

 level sealed

 check suite://meal/practicality@v2

Prompt text is one implementation detail inside identity, not a substitute for the contract. Reviewers inspect inputs, outputs, authority, and evaluation hooks. Maintainers version the template with the decision. See a contract, not a prompt for how this discipline changes code review.

A cognitive unit is a judgment with a contract, not a prompt with a name.

The cognitive unit · Ch. 2

Evaluation, authority, and composition

A cognitive unit without a suite is a hypothesis. Naming is step one. Evaluation is step two. Suites attach to identity, the decision sentence and template version, not to a model SKU floating in configuration. When AssessMealPracticality@v2 ships, published figures accompany the template hash and model pairing that produced them. That pairing is the warranty: change the model without remeasurement and the published numbers no longer apply. See reliability for what figures mean in production.

Contracts also declare what a cognitive unit may not decide. Meal Companion cognitive units may not diagnose medical diets, override allergies, or complete purchases. Invoice cognitive units may not approve preferential tolerance when organisational policy is unset, they refer to a clerk with authority. Explicit limits prevent scope creep disguised as capability. Those limits appear as refer branches and deterministic gates, not as hopeful instructions at the bottom of a prompt.

cognitive unit shapes, interpreter, generator, critic, judge, describe typical I/O patterns and failure modes. They do not change the one-decision rule. CritiquePlan is critic-shaped, but it still owns only material weakness identification, not repair. Shapes help design consistent interfaces across a library without becoming an excuse to merge critic and composer because both "deal with plans."

Agents orchestrate cognitive units toward a goal. Skills package known multi-step capabilities. Neither replaces the cognitive unit primitive. When a Skill performs invoice extraction, field-level cognitive units still own individual judgments inside the procedure, and the Skill does not absorb them into one prompt. See decide, perform, pursue for how composition responsibilities sit above a single edge.

Callers depend on the decision contract, what judgment is delegated, what inputs are required, what returns are possible, not on which model, retrieval stack, or few-shot block currently implements it. That black-box property is encapsulation applied to cognition. Implementation may begin as a single zero-shot call and evolve into multi-stage reasoning with critics and specialist models. None of that necessarily changes the architectural responsibility, if the contract stays stable and suites prove behaviour.

What to do next

The starting point for any cognitive unit is stating the open decision in one sentence that could be answered wrongly, then declaring inputs, outputs, abstention, and purity before writing the body. A suite binds to identity, and published figures ship with the template and model pairing. Compounds split until each named edge matches one judgment.

See one cognitive unit, one open decision and three rings of a cognitive unit.

Read next: One cognitive unit, one open decision.