A PM writes a 400-line spec. She reads the first 50 lines and the last 20, then skims the rest.
The 330 lines in the middle — business rules, edge cases, constraint definitions, the stuff that decides whether the feature works — go unread.
The engineering lead opens it. Reads the overview, skims the requirements table, jumps to the technical constraints at the bottom. That same 330-line middle stays unread by a second human.
Then he hands it to the agent. The agent reads every line. All 400. It does not skip, does not skim, and it implements exactly what the spec says — including the three contradictions between line 87 and line 312 that nobody caught because nobody read both lines.
Two weeks later the feature ships with a critical defect. The PM blames the agent. Engineering blames the spec. The spec blames nobody, because it is a markdown file, and markdown files do not defend themselves.
That scene, from Technomanagers, is the cleanest picture I've seen of the real problem. Two readers sit on either side of the same document with opposite failure modes. The humans skim and miss things. The agent reads everything and misses nothing — including the mistakes.
Last week this column argued about whether the PM role survives the demo-before-memo shift. This week the question narrows to something more concrete: what artifact does the PM actually produce now, when one of its readers is a machine that never gets bored?
The debate everyone is having is the wrong one. Peter Yang put it plainly on X: "What do people include in their product specs these days to make them friendly and concise for both humans and agents? Or two separate sections for each?"
The answers he got are a map of the tempting fixes. One camp writes two sections. One camp is reportedly retreating to writing specs by hand, wanting agents to "touch them very little." A third camp barely writes specs at all — a stream-of-consciousness prompt, iterate from there.
Each of these half-solves the problem, and it's worth being precise about which half.
Start with two artifacts. The logic is clean: a business-facing document and a machine-readable spec, each tuned to its reader. The BA-Squared writeup names the flaw exactly — maintaining two parallel artifacts doubles the documentation burden and introduces drift. The two documents fall out of alignment and nobody catches it until something has been built wrong. You've traded one contradiction between line 87 and line 312 for a contradiction between two files.
The format fixes are more interesting. Technomanagers makes a strong case for HTML as the spec layer: collapsible sections so the PM drills in only where needed, embedded mockups instead of a Figma link in another tab, and color-coded statuses — green for finalized, yellow for review, red for placeholder.
The economics check out. A markdown spec costs three to ten cents in tokens; an HTML spec costs ten to forty. But trace it downstream — skimming leads to missed contradictions, which lead to rework cycles at five to fifty dollars each. Two or three cycles and you've burned up to $150 and days of calendar time. The token overhead is noise. The rework is the signal.
But notice what HTML actually fixes. It fixes readability. It makes the human more likely to read the middle 330 lines. That's real, and it's not nothing.
It does not fix the thing the agent gets wrong. And the thing the agent gets wrong is not the words.
Here is the reframe. The agent's fatal weakness isn't that it can't read prose — it reads prose better than any human on the team. Its weakness is that it can't read the surround.
Tianpan's writeup on docs for agents has the sharpest version of this. A senior engineer spent two days chasing a deployment bug that was the agent's fault. The agent had read a runbook last updated in 2023, faithfully followed step three, and ran a command that no longer existed.
The runbook still rendered fine. The screenshots were even still legible. But it had silently become hostile to a reader who couldn't tell the surrounding context was stale.
A human reading that runbook clocks the problem in five seconds. The screenshot shows last year's UI. The Slack handle in the "ping if broken" line belongs to someone who left. The version pin is three majors behind. None of that is in the text. It's in the surround, and the human integrates a hundred small freshness signals before reaching step one.
The agent reads the same page with none of that scaffolding. It has no model of which docs are canonical versus a half-finished draft someone abandoned in 2022. It follows the steps with identical confidence whether the doc is the team's gospel or an experimental brainstorm that should have been deleted.
That asymmetry is the whole game. Humans tolerate ambiguity that agents resolve wrong. Agents tolerate density that humans bounce off.
Humans tolerate ambiguity that agents resolve wrong. Agents tolerate density that humans bounce off. That asymmetry is the whole game.
And it produces failure modes you only see in production. The synthesis-across-tiers failure: the agent retrieves a blessed architecture doc and an exploratory proposal that contradict each other, splits the difference, and hands the engineer a plausible architecture that no team actually built.
The one that should scare every PM is scope collapse. An agent reads "we use Postgres for everything" — written by the platform team, about platform-team systems, with an implicit "we" that meant their team.
The agent generalizes it to the whole company, including the analytics platform running on Snowflake. The prose was correct. The scope was assumed. The human would never have made that leap because the human knows who wrote it and what "we" meant.
This is why the two-audience framing is a distraction. You cannot format your way out of scope collapse. Collapsible sections don't tell the agent that "everything" meant "our stack." A prettier document with a stale runbook inside it is still a stale runbook.
The signal the agent needs isn't in the layout. It's in the metadata that a human absorbs for free and an agent cannot infer at all — freshness, authority tier, locked-decision status, scope boundary.
So the new craft is encoding the surround directly into the spec. Not two documents. Not two sections. One layered artifact whose real innovation is the context around the words.
Some of this is already showing up in the format work. Those green-yellow-red status colors from the HTML spec? That's freshness and authority, rendered so the agent can read it as text rather than infer it from a stale screenshot it never looks at.
Obvious's spec template goes further and makes two surround-signals mandatory. Scope boundaries: what this intentionally does not cover, and why — stated so the agent doesn't gold-plate by building email notifications you never asked for. And decided: the choices you've already locked, "which the agent will not reopen without asking."
Read those two fields against the scope-collapse failure and they're the exact antidote. A scope boundary is a human writing down the "we" that the agent would otherwise guess wrong. A locked decision is authority tier made explicit — this is settled, not up for synthesis.
None of this is exotic. It is the discipline of finally writing good requirements — clear, explicit, structured, complete enough that the executor doesn't fill gaps with assumptions. As ReadMe puts it: where a human guesses and moves on, a model guesses and submits.
The urgency is that the second reader is now the primary one. Per Amplitude, in the first 18 days after it relaunched its docs, LLM crawlers requested 198,843 page views. In the same window, 37,561 unique humans loaded 124,044 pages.
The bots out-read the humans, and they weren't winning a popularity contest — they were answering questions on behalf of people who never visit the docs at all. Roughly 80% of internal knowledge bases go stale within months, and the staleness stays invisible until an agent confidently teaches it to someone.
So stop writing the second spec. Stop debating the second section.
Write one artifact, and spend your new effort on the layer the agent literally cannot see: how fresh this is, who blessed it, what's locked, and where the boundary sits. The words were never the problem. The words are the one part the agent already reads better than you do.