Adopting cognitive unit in existing code

Open any codebase built on language models and count the model calls. In a mature system there will be dozens or hundreds. In most codebases, almost nothing surrounds them: no stated purpose, no evidence, no cost attribution, no way to know whether one service's version matches another's. The judgment already exists. It lives inside a prompt string, a chain template, or a monolith function named processRequest. Adoption does not begin with a shared library platform. It begins with inventory: find call sites, write one sentence naming the judgment each call owns, then measure before packaging.

Helpful context: Start with one bounded judgment defines the first slice. Tuning by wrapping improves cognitive units without rewriting loops. Cognitive Units defines what the extraction moves toward. This page is the migration playbook for codebases that already call models.

Order of return

The cognitive unit recommends steps in order of return because the cheapest steps often produce most of the value. Skipping them produces wrappers without names, which is ceremony rather than migration.

The first move finds call sites and writes one sentence naming the judgment each call owns. The second labels purity levels, and accidental world-writing or hidden composites surface quickly at this stage. The third splits compounds so each cognitive unit owns one open decision. The fourth moves closed work into deterministic guards and code. The fifth attaches evaluation suites and runs shadow eval against old behaviour. The sixth cuts over when parity is demonstrated. Library packaging comes last, only when evidence supports semantic versioning.

Naming alone often reveals duplicate work. Two services may both "assess practicality" with different prompts and no shared suite. Three teams may draft clarification questions with incompatible conduct. Inventory forces those duplicates into the open before anyone argues about framework choice.

Count callsName judgmentsLabel purityReturn closed workShadow evalCutoverPackage

Adoption is inventory before infrastructure. Shadow eval before cutover.

What this looks like in practice

Extracting the busy-evening check from a monolith meal-planning prompt into AssessMealPracticality illustrates the full adoption arc. The legacy path embeds practicality inside a single large prompt: generate meals, check allergies inline, mention busy days in prose instructions, return JSON. It works on demos. It fails opaquely when Tuesday's effort metadata is wrong because nobody can test practicality in isolation.

Adoption proceeds in order. First, naming: "Does this candidate fit this evening given schedule and effort limits and endorsed constraints?" Second, splitting: allergy enforcement moves to deterministic gate code while one open judgment remains in the cognitive unit. Third, shadow: the new cognitive unit runs alongside the old prompt path on held-out cases with outputs compared automatically. Fourth, eval parity: the suite shows the new cognitive unit matches or exceeds old behaviour on stratified cases covering busy Tuesday, normal Thursday, and missing effort data. Fifth, cutover: the call site invokes the cognitive unit by name and the old embedded check is removed. Sixth, library: after stability, the cognitive unit publishes to the meal-planning domain library with semantic versioning, owner, and substitution rules.

Parallel run before cutover is how adoption avoids "we rewrote the prompt and hope." Eval compare is the gate. Packaging freezes what is understood, not what is guessed.

What not to do first

Beginning with a shared library platform, a universal agent framework, or a rewrite of every prompt produces premature infrastructure without named judgments: orchestration around nothing measurable. That failure mode looks responsible because everyone is busy building wrappers.

A common anti-pattern wraps every call in the same boilerplate without naming the decision. The wrapper adds indirection. The sentence that names the judgment is the migration. Without it, shadow eval has nothing to compare and suites have no decision class.

From experimenting to governing describes when shared libraries earn organisational policy. Premature discipline warns against publishing before boundaries stabilise. Adoption respects both: extract and measure first, publish when evidence supports semantic versioning.

Purity labelling and closed work return

Purity labelling surfaces hidden composites quickly. A call that reads working state, writes memory, and decides fit is several responsibilities glued together. Splitting until each cognitive unit owns one open decision follows from purity and the five levels.

Closed work belongs in code, not in prompts that "usually" enforce rules. Portion math, schema validation, allergy enforcement once knowledge is endorsed: returning these to the deterministic shell before debating model upgrades produces immediate reliability gains. See price of closed work left open when exact operations remain inside interpretive paths.

Shadow eval in detail

Shadow mode runs the new cognitive unit alongside the legacy path without user-visible cutover. Outputs compare on held-out cases stratified by failure mode: busy evening, missing metadata, allergy conflict, incomplete week representation. Disagreements are logged with enough context to label whether legacy or new behaviour was correct.

Parity does not require identical text. It requires equivalent judgment under the spec standard. If the legacy path guessed when effort data was missing and the new cognitive unit abstains, parity may mean the new path is strictly better when the spec requires abstain. That decision belongs in the cutover record.

Cutover is reversible for one release cycle. The legacy path stays behind a flag until production metrics and eval regression stay clean. Reversibility is how adoption avoids big-bang hope.

Team coordination and progress

Adoption touches platform and product boundaries. Platform may supply wrappers, logging, and eval infrastructure. Product teams supply domain sentences and case labels. The architect supplies map alignment so extracted cognitive units match library placement intentions. Without coordination, platform builds generic tooling while product extracts duplicates that never reach shared libraries.

Adoption progress is visible in artifacts, not in meeting sentiment. The meaningful metrics are how many model calls now have one-sentence judgment names, how many named cognitive units run in shadow mode, how many cutovers completed with documented parity decisions, and how many duplicates collapsed before library promotion. A team that wrapped every call but named none has motion without migration.

Weekly review can use a simple table for one service: call site, judgment sentence, purity label, shadow status, suite status, owner. The table exposes whether adoption is inventory discipline or framework theatre. When shadow disagreements cluster on one class, that class becomes the next extraction target rather than another wrapper template.

The enterprise parallel

Invoice intake adoption follows the same order with different domain sentences. A monolith extraction prompt may hide vendor identification, line matching, and exception classification in one chain. Adoption names each judgment, moves amount reconciliation to deterministic code, shadow-evaluates field interpretation cognitive units against legacy output on stratified invoices, and publishes to the domain library only when substitution rules and procedure suites justify semantic versioning. Clerks care about parity on disputed lines, not about internal package names.

The two cheapest steps, naming and purity labelling, often produce most of the value.

The cognitive unit . Ch. 21

Common mistakes

Big-bang rewrite. Migration wins come from one bounded judgment at a time, aligned with one bounded judgment. Rewrites bundle risk without producing evidence.

Cutover without shadow. Hope is not a migration strategy. Parallel run is the gate between legacy and named.

Publishing duplicate cognitive units under different names. Inventory collapses duplicates before library promotion, preventing shared libraries from accumulating redundant entries nobody maintains.

Ignoring conduct during parity checks. Matching answer text while escalation behaviour diverges recreates pilot inconsistency inside production.

What to do next

Counting model calls in one service, writing one sentence per call naming the judgment, and picking the call whose failure hurts most is how the first extraction begins. Shadow eval on that judgment produces the evidence cutover needs. Once stability holds, library publication with semantic versioning makes the named judgment available beyond the original team.

See one cognitive unit, one open decision, finding the weak decision, and behavioural standards across teams for what must travel with shared reuse.

Read next: Behavioural standards across teams.