Tuning by wrapping

You have AssessMealPracticality scored properly on a stratified suite. Eighty-four percent is not enough for the authority you want. The instinct is to open the template and edit. That instinct is close to the worst available option.

Helpful context: Encapsulation principle keeps cognitive units behind contracts. Substitution rules govern library versions. Evaluation as engineering supplies the suite wrappers must move. This page is the Ch. 13 pattern for improving without rewriting identity.

What a rewrite costs

Evidence belongs to an exact template text and model pair. Editing the body means the numbers describe something you are no longer running. You throw away the score, class breakdown, intervals, and determinacy anchor. The new cognitive unit has no baseline until a new suite record exists. That gap between rewrite and re-evaluation is where teams operate without evidence, shipping changes they cannot compare to what came before.

Evidence dies when the template changes. Teams that rewrite weekly for demo polish never accumulate trustworthy eval history. Operators cannot tell whether production improved or merely changed identity. The pattern compounds because each rewrite resets the clock, making it impossible to build the longitudinal data that would eventually justify confidence.

After a rewrite you have a new cognitive unit with no evidence. After a wrapper you have the same cognitive unit with more evidence.

The cognitive unit, Ch. 13

Rewrite

New identity, lost baseline, non-transferable edit

Wrapper

Same contract, added evidence, composable pattern

Wrappers preserve identity and let reliability spend stay attributable to the combinator.

Wrappers compose

A combinator takes a cognitive unit and returns a cognitive unit with the same decision, holes, and result shape, including abstention and referral. Callers are drop-in. Wrappers compose because the output is still a cognitive unit with the same contract, which means multiple wrappers can stack without changing what the caller expects.

Wrapper	Buys	Typical spend
sample_n	Stability via majority	3x or 5x money
retry_until	A checkable property	Variable
with_critic	Depth against shallow answers	About 2x
cascade	Quality with cheaper models first	Less money, more time on escalations
route	Mixed case distributions	About 2x

Sampling addresses variance, not bias. Three identical wrong answers vote for the error. Preconditions, abstention, and deterministic fallbacks belong outside cognition where they are exact. See deterministic guards before cognition. The distinction matters because a team that samples a biased cognitive unit three times has spent three times the money to be three times as confident in the wrong answer.

Library substitution versus template edit

After eval, swapping AssessMealPracticality v2 from the meal-planning domain library per substitution rules keeps the same contract for callers. The agent loop does not change. Evidence transfers through substitution policy, not through silent prompt edits in production. The substitution is declared, rollback-capable, and comparable against the prior version on the same regression set.

Substitution is wrapping at library boundary: new implementation, same interface, declared rollback path when regression fails. It is the mechanism by which a team improves an edge without the caller knowing or caring, and without the evidence trail breaking.

What this looks like in practice

GenerateCandidates stays fixed. A seasonal filter wrapper removes out-of-season proposals before the suite runs. Contract unchanged, baseline preserved, wrapper effect measurable on the same regression set. The improvement came from a preprocessing step that removed noise from the cognitive unit's input, not from rewriting the cognitive unit itself.

A busy-evening preprocessor flags evenings before practicality assessment. Closed routing in code, open judgment in the cognitive unit. Cost drops because population shrinks before the expensive call. The preprocessor is deterministic code attached to a cognitive unit rather than woven into its template.

When critique failures drove loop multiplication visible in cost per decision spreadsheets, adding with_critic on ComposeWeek addresses the root cause. Spend rises on that line. Loop iterations may fall enough to net savings, because a slightly more expensive call that terminates the loop one iteration earlier saves the full cost of a subsequent compose-critique-patch cycle.

When the body must change

Sometimes the decision itself is wrong, the holes are mislabelled, or the suite exposes a systematic misreading that no wrapper can fix. Then rewrite deliberately: treat the result as a new identity, rebuild evidence from scratch, and publish under substitution rules. Wearing last quarter's figure on new text is dishonest accounting that misleads operators about production confidence.

The signs that the body must change include a rubric and decision class that no longer match (practicality conflated with variety), an abstention shape wrong for the authority model, and systematic bias that sampling amplifies rather than reduces. Each of these signals a problem with what the cognitive unit is doing, not how reliably it does it. Wrappers fix reliability. Rewrites fix identity.

Wrapper selection guide

Matching the wrapper to the failure mode visible in the suite prevents overspend. High variance with low bias on AssessMealPracticality calls for sample_n with majority vote, because the cognitive unit is right on average but inconsistent across runs. Shallow compose that misses critique criteria calls for with_critic before touching the template, because the weakness is depth of reasoning rather than correctness of the base answer.

Mixed easy and hard cases on one edge call for route or cascade rather than one global stack, because a single policy overpays on easy cases or underpays on hard ones. Transient format failures call for retry_until schema valid with a cap to protect the time budget. Wrong wrapper choice raises cost without moving accuracy. Measuring on the same regression set after each wrap is what distinguishes tuning from guessing.

Transfer across teams

Wrappers documented as combinators transfer across products that share contract shapes. A sample_n policy for household-fit judgments applies wherever that judgment appears. Central reliability engineering can own wrapper recipes the same way platform teams own retry policies for HTTP clients. This is possible because the wrapper is decoupled from the cognitive unit's internal template. A rewrite, by contrast, does not transfer. It forks evidence and produces a per-product drift that makes shared learning impossible.

Cost of wrappers on the spreadsheet

Every wrapper appears as a line multiplier on cost per decision for that edge. Sample-three on AssessMealPracticality triples the row. Finance approves when suite movement and autonomy return justify the multiplier. Finance should challenge when the multiplier rises without before-and-after eval on the same regression set.

Documenting wrapper rollback matters: if v2 wrap fails regression, revert to v1 wrap or bare edge with known baseline. Substitution rules apply to wrapper stacks the same way they apply to library versions. The rollback path makes the investment reversible, which is what allows teams to experiment without committing irreversibly to higher spend.

Evidence discipline

Claiming wrapper improvement without the same regression set before and after is not evidence. Comparing scores across different template identities is not evidence. Skipping documentation of which combinator changed when suite movement appears in release notes is how teams lose the causal chain between investment and outcome. Evidence discipline is what separates tuning by wrapping from prompt roulette.

Quarterly reliability review can use one table: decision class, wrapper policy, monthly spend, suite delta, autonomy delta, determinacy ceiling note. Empty cells mean theatre. Filled cells mean paying for reliability is operational.

Pre/post processors versus combinators

Preprocessors shrink input before the cognitive unit runs (seasonal filter, busy-evening flag). Postprocessors validate or reshape output before the caller sees it. Both preserve contract when they keep the same decision class and result shape. When a preprocessor changes the decision (drops evenings entirely), the contract may have changed. Review with encapsulation and eval ownership before shipping.

Combinators like sample_n wrap the call itself. Pre/post processors sit adjacent. All three appear on cost spreadsheets as multipliers or volume reducers. Naming them explicitly keeps tuning history attributable so that quarterly reviews can trace improvements to specific investments rather than to vague "we worked on it."

Wrapper experiments in staging

Running wrapper experiments in staging against the same regression set before production promotion catches sample bias and critic loops that multiply cost without moving accuracy. Staging evidence protects production from experiments that looked promising on demo utterances but fail on the distribution of real traffic. Production promotion follows staging evidence, not intuition about what should help.

Treating wrapper changes like schema changes (logging version, running eval diff, requiring rollback paths) prevents wrapper sprawl. Each layer has a named owner and a suite that proves improvement on held-out cases. Cap wrapper depth so that stacking does not produce complexity that nobody can reason about. Wrappers are where teams improve prestige edges without forking cognitive unit identity, but that power requires discipline to avoid recreating prompt fork culture inside supposedly sealed packages.

What to do next

The entry point is picking one underperforming edge with a stable decision class and trying one wrapper before any template edit. Documenting wrapper policy on the architecture artifact means finance sees reliability spend as a deliberate investment. Blocking promotion if a wrapper improves mean score but breaks regression cases protects the evidence base. Using library substitution when v2 exists with an eval record, rather than editing v1 in place, preserves the comparison surface that makes future improvements measurable.

Wrappers transfer across cognitive units with the same contract shape. See paying for reliability, evidence dies on rewrite, and feature cost versus decision cost.

Read next: Paying for reliability.