Nobody reads the FEATURE_SPEC.md. What's the Solution?
Here is what fixes it.
A PM writes a functional spec in a markdown file. It is 400 lines long.
PM reads the first 50 and the last 20 and skims the rest. The middle 330 lines contain the business rules, edge cases, and constraint definitions that determine whether the feature works or does not.
Then sends it to engineering.
The engineering lead opens the file. He reads the overview section. Skims the requirements table.
Jumps to the technical constraints at the bottom. The 330 lines in the middle remain unread by a second person.
He hands it to the AI agent.
The agent reads every line. All 400 of them. It does not skip. It does not skim.
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.
This is the most common failure mode in AI-native product development. And it did not start with AI.
The Problem That Existed Before Agents
Here is the uncomfortable truth. PMs have been skimming their own specs for years.
Markdown made specs easy to write. It did not make them easy to read.
A 400-line markdown file has no visual hierarchy beyond headers and bullets. No collapsible sections. No embedded mockups. No way to draw your eye to the three lines that matter most out of the 400.
Before agents, this was tolerable. Not good, but tolerable. Because the humans on the other side of the spec had a safety net.
Engineers asked clarifying questions. “What did you mean by this requirement?” “Does this apply to logged-out users too?” “This contradicts what you said in section 3.” Those questions caught the misalignments that skimming introduced.
Sprint reviews caught the rest. You shipped a version. It was wrong. You discussed it. You adjusted. The feedback loop was two weeks. The cost of misalignment was measured in sprints, not dollars.
AI agents removed every one of those safety nets.
The Spec-Driven Development Connection
We wrote about this problem in our article on Spec-Driven Development. The core argument was that a spec is a contract, not a document. It should be a behavioural specification that defines what the system must do, not a technical specification that prescribes how.
That argument stands. But it is incomplete.
A behavioural spec only works if someone reads it. A perfectly written contract that neither party reads is not a contract. It is paperwork.
Most PMs write behavioural specs in markdown. Those specs contain precise requirements. Constraint definitions. Edge case handling rules. Confidence thresholds. Fallback behaviours. All the things that separate a spec from a prayer.
Then nobody reads them.
The Solution: HTML as the Spec Layer?
AI agents generate HTML as easily as they generate Markdown. For the agent, the effort is identical. For the human, the difference is enormous.
An HTML spec can have collapsible sections. The PM sees high-level decisions first and drills into detail only where needed. Engineering sees the data model expanded with product context collapsed. Same document, different views, one handoff.
It can have colour-coded requirement statuses. Green for finalised. Yellow for needs-review. Red for placeholder. The PM sees at a glance which parts of the spec are done and which are still unfinished thoughts pretending to be requirements.
It can embed mockups inline. Not a link to Figma in another tab. A rendered visual sitting next to the requirement it represents. You see what you are specifying as you specify it.
It can use tabs to separate product context, behavioural requirements, technical constraints, and verification criteria. Each audience reads the tab that matters to them. Nothing gets lost crossing the handoff.
This is the Engagement-Quality Loop. Better readability leads to more engagement. More engagement leads to more edits. More edits lead to higher quality specs. Higher-quality specs lead to fewer implementation cycles. Fewer cycles mean lower compute cost.
The Costs and Limits
The token overhead is real. The ROI is better.
A markdown spec costs $0.03 to $0.10 in tokens. An HTML spec costs $0.10 to $0.40. Roughly 3 to 5x more.
But trace the cost through the chain. The markdown workflow leads to skimming, which leads to missed contradictions, which leads to rework cycles at $5 to $50 each. Two or three cycles, and you have spent $15 to $150 plus days of calendar time.
The HTML workflow costs $0.30 more upfront. You catch the contradiction before implementation. One cycle. $5 to $50. Done.
Less than 1% of tokens that most teams generate end up in production code. The rest goes into planning, iterating, and reworking.
The question is not whether the spec costs more tokens. The question is whether those tokens produce a spec someone actually reads.
The token overhead is noise. The rework is the signal.
When will markdown still win?
Short tasks where the output fits on one screen. Agent-to-agent handoffs where no human reads the document. Pure technical artefacts like type definitions and API schemas. If no human judgment is needed, use markdown. If human judgment is needed, use HTML.
A PM who does not spec is spending blindly. A PM who specs in a format nobody reads is spending with everyone’s eyes closed.
The Workflow
Five steps. Start tomorrow.
Spec in HTML. Prompt: “Create an HTML behavioural spec for [feature]. Collapsible sections. Colour-code requirements: green for finalised, yellow for review, red for placeholder. Embed mockups.”
Read your own spec. Open every section. Finalise every yellow. Remove every red. Do not send a spec with placeholder text to an agent. Every red line is a budget leak.
Identify decision nodes. Three to five points where human judgment matters more than agent capability. Business rules. Trade-offs. Prioritisation logic. These are the moments the PM earns their role.
Build micro-software for each node. Rule editors. Priority rankers. Trade-off sliders. Make decisions with full context. Cost: cents per tool. Value: precision instead of intuition.
Hand off clean. Fresh agent session. HTML spec as a single source of truth. One implementation cycle. Verify against the embedded checklist.
Total extra cost: $0.50 to $2.00 per feature. Total savings from eliminated rework: $10 to $200.
If this changed how you think about our Job Ready AI PM Cohort
(12 Weeks, ~50 Sessions, ~100 Hours, ~10+ Products built) ~goes deeper. Live cohort. Cohort registrations open. Limited seats. Fill this Form to Show Interest
More Resources
AI PM Course - (PMs at Microsoft, Coinbase, Indeed & 600+ PMs rated 4.9/ 5)
See testimonials and course detailsCrack AI Business Roles (Consulting, Category Management, General Manager) - Course Details
Crack AI Program Manager Roles - Course Details
About Author
Shailesh Sharma! I help PMs and business leaders excel in Product, Strategy, and AI using First Principles Thinking. Weekly Live Webinars/MasterClass ( Here )