A forty-page spec and a five-line Slack thread the next morning are the same failure.
I have watched three teams ship this way: supply-chain platforms at Dell, a 20-person AI creative team at Pixis, the data platform under InMobi’s ad exchange. Each one wrote specs that got longer every quarter. Each one still had the same five questions land in chat the morning after the doc went out.
That is not a reading problem. It is a design problem. The document was built to survive scrutiny, not to produce action. I run the spec-driven process for this site now, one spec per feature in specs/, and the difference between a spec that works and a spec that doesn’t has nothing to do with length.
So that’s today’s post.
Today’s Post
Why the thick spec and the ignored spec are the same document, in six sections.
- Why the spec is doing the wrong job
- Thoroughness is not quality
- How CYA culture writes documents nobody opens
- The three questions that carry the whole thing
- The one-page spine, and how this site runs it in public
- Why conversation has to come before the document
1. The spec is doing the wrong job
Most teams think a spec fails when it is too thin. The real failure is almost always the opposite.
Completeness is not the same job as alignment. A spec built for completeness tries to hold every decision forever. A spec built for alignment tries to get four functions moving in the same direction by Monday.
When a PM treats the spec as the place where every decision must live, the document turns into a defensive wall. It is written to survive people who were not in the room. It is written to pre-empt every objection before it is raised. Forty pages later, it functions as a security blanket for the author and a skippable PDF for everyone else.
I would grade a spec that tries to be an encyclopedia a 3/10, no matter how well-researched each section is.
Here is how the spec-driven process on this site avoids that trap. Every feature on this site has a spec in specs/, and each one is written before the code, not after. The Swiggy-style ETA estimator spec freezes the formula, the output shape, and the acceptance threshold, nine of ten fixtures within three minutes, in under a page. The formula could fill ten pages of derivation. It doesn’t need to.
The team does not need a monument. They need a shared picture of what they are building, why it matters, what success looks like, and which tradeoffs are already made. Everything past that belongs in tickets, in design files, and in the heads of the engineers who build the thing, not in one canonical scroll pretending to replace judgment.
2. Thoroughness is not quality
Organizations reward thickness. A long spec signals seriousness. A short one signals laziness. That reward structure produces bloat, one paragraph at a time.
Ambiguity insurance: the PM adds a paragraph because an unresolved question feels dangerous to leave unresolved on the page, even when it is genuinely unresolved in the room. Legal gets folded in because nobody wants to be the one who “forgot to document” a risk. Every stakeholder wants their concern reflected somewhere in the same file, as if inclusion were the same thing as agreement.
None of that material reduces risk. It relocates risk into a document dense enough that nobody reads it closely enough to resolve anything.
Quality in a spec is not page count. It is whether the team can act without re-asking the same questions. This is the same trap the outcomes post on this site names for metrics: a dashboard that looks thorough and a spec that looks thorough fail the same way, they measure the wrong thing. Usage tells you a feature is visible. Page count tells you a PM was busy. Neither tells you whether the thing worked.
The acceptance criteria on this site’s example specs are written as binary checks for exactly this reason. A criterion you cannot fail is not a criterion, it’s a mood.
3. CYA culture writes documents nobody opens
Some teams do not write long specs because the work demands it. They write long specs because the culture punishes a visible gap harder than it punishes slow execution.
When the primary job of a document becomes coverage, the prose changes shape. Sentences hedge. Sections duplicate the same requirement three ways. Every addition is a small insurance policy against blame six weeks from now.
That produces a document that is defensible and useless in the same breath. It proves someone wrote something. It does not prove the team agrees on what happens next.
The skim trap: engineers learn to skim because skimming is the rational response to a document where the signal is buried under compliance filler. Designers learn to wait for the meeting because the meeting is where the actual decision surfaces. Product learns to dread the rewrite cycle, because each revision is another round of performing diligence for an audience that will not read the new version either.
Ad-tech solved a version of this problem years ago by refusing to let one party grade its own work. Nobody lets an ad network report its own install numbers unaudited, the industry built an entire referee category, the MMP, to check the math independently. A spec that only the author reads and only the author defends is marking its own homework the same way.
None of that gets solved by adding detail. It gets solved by changing what the document is for.
4. The three questions that carry the whole document
A readable spec answers three questions with uncomfortable clarity. Everything else is optional.
What are we building and why? Not a feature list dressed up as strategy. The customer problem, the business reason, the constraint that makes this the right bet now. Read only this section and you should understand the intent without a glossary.
What does success look like? Outcomes, signals, the minimum bar for “this worked.” If you cannot state success without citing internal politics, you have not finished defining the goal, you are still negotiating it.
What are we deciding now, and what are we explicitly not deciding? Tradeoffs are the actual heart of product work. A spec that pretends every choice is obvious gets rewritten in code review two weeks later. Name the decision. Name its cost. Name what you are willing to be wrong about.
specs/templates/ on this site has one template per spec type, content-schema, ai-feature, feature, component, and every one of them opens with these same three questions before a single field or endpoint gets named.
5. The one-page spine, and how this site runs it in public
The best specs share a structure: a short spine of decisions and context, then links outward for depth.
The spine: fits on one page, or two for a genuinely complex problem. It is written for the people who must align before work starts, product, design, engineering, and whichever partners actually block or accelerate the effort.
The links: point to research summaries, flows, technical notes, analytics views, and legal requirements. Those artifacts can run long. They should run long when the detail earns it. The spine stays short because its job is not to contain the universe, its job is to force alignment on the small set of choices that otherwise leak into Slack as thrash.
This site runs that spine at the project level too, not just per feature. specs/ROADMAP.md is one file. Every feature, partial or shipped, has a row. Every row links to its spec and carries a status. There is no separate backlog living in a second tool that drifts out of sync with the first.
The model respects attention and expertise at the same time. The engineer who needs the edge-case list opens the appendix. The designer who needs the user journey opens the research doc. The reader who needs the narrative reads the first page and stops there, correctly.
What does not work is forcing every reader through the same forty-page funnel because one PM wanted a single file to rule them all.
6. Why conversation has to come before the document
No document eliminates ambiguity. At best, a spec compresses ambiguity into a visible decision.
The teams that ship well treat the spec as the output of a conversation, not a substitute for one. They have the hard discussion first. They write the spec to record what got decided, not to avoid having the discussion at all.
That order matters more than any formatting rule in this post. When the spec leads, the document is a wish, people sign off on paper without understanding it, and the real conflicts surface during implementation, the single most expensive place to find them. When the conversation leads, the spec becomes a record, and it is easy to keep short because the group already did the painful alignment work in the room. The words on the page map to something the whole team remembers living through.
This is also where implementation detail belongs, and it isn’t the spine. Data models, API shapes, exact error copy, those items matter, but they do not need to share a narrative with the strategy section. They need an owner, a ticket, and a place where a specialist can move fast without re-reading a page of company mission first.
A common failure worth naming directly: confusing documentation with decision-making. You can describe a feature beautifully and still leave the team without a decision on scope, on the success metric, or on what happens when reality disagrees with the plan. The team will keep asking, and the fix is never another paragraph of explanation. The fix is stating the decision, even the uncomfortable one. “Ship without X.” “Defer Y to phase two.” “We are optimizing for speed over polish in the first release.” Three short sentences, and each one saves a week of thrash later.
Takeaways
Six panels, one per section. The callout is the thesis, and the test to run on the last spec your team shipped.
Final Words
Most teams have the discipline to write long specs and not the discipline to write short ones. Thoroughness feels safer than judgment, and it produces a document that impresses stakeholders and exhausts builders in the same breath.
Pick the last spec your team wrote. Check whether it answers the three questions in section 4 in the first page. If it doesn’t, the length was never the problem, the missing decision was.
Reply and tell me what you found.
Cheers, Hoshank