spec ambiguity
When the Spec Runs Out
2026 · 5 min read
A modern interconnect specification runs two hundred and fifty pages, defines every field width down to the bit — and still leaves the hardest behavior in the whole document to a sentence with two defensible readings.
We spent a recent project with a spec like that. The register maps were pristine. The packet formats were precise. The state machines had diagrams. And buried in the flow control section was a rule that had been read a hundred times without anyone noticing it could mean opposite things.
The sentence said a certain behavior applies "thereafter." Every engineer who read it assumed they knew when "thereafter" begins. The problem: the spec never says. One reading ties the behavior to a transaction. The other ties it to the life of the link. Both readings are grammatically flawless. They produce hardware that behaves differently, on the same input, forever.
Why the obvious interpretation is the dangerous one
Ambiguity in a spec doesn't feel ambiguous when you read it. Your brain resolves it silently, picks the reading that matches your mental model, and moves on. That's why it survives review after review — every reader is confident, and no two readers are confident about the same thing.
The danger concentrates where the stakes are highest. The rules that govern error paths, reset behavior, and races between concurrent events are exactly the rules written fastest, latest in the schedule, by the person most tired of writing the document. The bit field tables got four tables of review. The recovery semantics got a paragraph.
What a professional reader looks for
Reading a spec for modeling is different from reading it for implementation. The implementer asks "what do I build?" The modeler asks "where does this document stop deciding?" — because every place the spec stops deciding is a place where the model and the RTL will eventually disagree, and nobody will know which one is wrong.
- Adverbs carrying load. "Thereafter." "Subsequently." "Immediately." Each one is a timing decision wearing a word as a disguise.
- Internal contradictions between the tables and the prose. Field-width tables and narrative sections are written at different times by different hands. When they disagree, the discrepancy itself is the finding.
- Examples that are not normative — but everyone treats them as if they were. An illustration of one case quietly becomes the definition of all cases.
- Sentences that appear twice, slightly differently. Copy-paste editing is where definitions fork.
In that project we catalogued thirty of these. Ten of them genuinely didn't matter. Nineteen had one obvious right answer once you noticed the question. One changed the state machine.
The deliverable isn't the model
Here's what surprised us, though it shouldn't have: the most valuable output was not the model, but the ambiguity list. Thirty questions, each with the two readings, the page numbers, and our recommendation. A team can own a spec for a year and nobody has ever shown them where it stops deciding.
A model built on a silent guess will faithfully reproduce that guess forever. A model built on an explicit question makes the whole team decide — once, in a conference room, instead of in the field, after silicon comes back.