Grep the Consumers Before Writing the Producer

I specified a dataclass field name. The agent built the module to spec. Then the agent stopped, ran a static check of the existing callers, and flagged:

The consuming interface expects a different field name. The spec shape would break integration.

The drift was orchestrator-side. I had written Score.value: Decimal into the dispatch prompt without grepping what the existing callers actually expected. The callers expected score_total: Decimal. Different name, same type, functionally invisible — except at the call-site where the agent was about to write the wiring.

The Dispatch Prompt Is the Highest-Leverage Document

The dispatch prompt is the highest-leverage document the orchestrator writes. Every ambiguity in it becomes a function signature choice at implementation time. Getting the signature wrong isn't a typo; it's a design decision that propagates through every downstream wire.

The Rule

Before specifying any output shape — function signature, dataclass field name, return type — in an implementation dispatch prompt, grep the existing callers to verify the proposed shape matches their expectations.

The mechanical version, operationalized in every dispatch prompt after this incident:

## Consumers of this output

- `module_a::function_b` — expects field `score_total: Decimal`
- `module_c::function_d` — expects field `score_total: Decimal` via keyword arg

(If no consumers exist: "This output has no existing consumers;
 shape is proposed for validation at first wiring.")

That section became non-optional in every dispatch prompt after this incident. Its absence is now a smell — if the prompt doesn't enumerate consumers, the prompt isn't ready to fire.

The Orchestrator's Correctness Layer

The orchestrator's job is the correctness layer. The orchestrator can specify what an agent builds, but the orchestrator cannot specify what the rest of the system expects — that's derived by reading existing code.

If the orchestrator shortcuts that derivation, the agent either catches the drift — in which case the agent did the correctness-layer work the orchestrator should have done — or doesn't catch it, in which case the drift ships.

The Transfer

Interface-first design in any multi-module system. When module A produces an output that module B consumes, the contract lives at B's expectations — not at A's specification.

A needs to match B. That only works if you know what B expects before you specify A. Grep is the forcing function.

The lesson: "I know what the callers expect" is rarely true. Grep is cheap. Assumption is expensive.

When you're dispatching an AI agent to build something that integrates with existing code, the hardest part is not writing the prompt. The hardest part is reading the consuming code carefully enough that the prompt matches what actually exists. Skipping that step is how you ship specs that pass review but fail wiring.