Why Specs Fail: The 5 Anti-Patterns
If you give a vague prompt to a junior engineer, they might ask clarifying questions. If you give a vague prompt to an AI agent, it will confidently build the wrong thing.
In the age of AI-assisted development, specification is no longer a "nice to have" document. It is the source code of source code.
Yet most product requirements documents (PRDs) are broken. They suffer from one of these five anti-patterns.
The "Figure It Out" Spec
The Symptom: A one-line Jira ticket. "Add a dark mode toggle."
Why it fails: The agent has to hallucinate the requirements. Where does the toggle go? Does it persist in local storage? Does it respect system preferences?
The Fix: Never write a "what" without the "how it behaves". If you don't define the constraints, the agent will invent them—usually poorly.
The Prose Novel
The Symptom: A 5-page Google Doc full of paragraphs, rambling context, and "it would be nice if..."
Can't complete purchase on mobile
User reports that the payment button is unresponsive on iOS Safari. Tried clearing cache, same issue. This is the 5th report this week.
Users prefer the new nav
Actually wait — 6/8 participants struggled with the dropdown. Need to revisit this. @Jake thoughts?
"I just want to see my order status without logging in every single time. Why is this so hard?"
Pricing page shows wrong currency
Multiple reports from EU users. Prices show USD despite locale being set to DE. Unclear if this is a frontend or API issue.
Dashboard data doesn't match reports
Enterprise customer threatening to churn. Revenue numbers on dashboard are off by ~15% compared to exported CSV.
P3 abandoned the task after 4 minutes. Said "I don't understand what this button does." This is our primary CTA.
Why it fails: Agents (and humans) struggle to parse dense prose into logic. Nuance gets lost in the noise. "It would be nice if" is interpreted as "Do this immediately" or ignored entirely.
The Fix: Structure beats length. Use bullet points, boolean logic, and explicit lists. An IntentSpec should look more like JSON than a blog post.
The Wishlist (No Acceptance Criteria)
The Symptom: A list of features without a definition of "done".
Why it fails: The agent can generate code that looks like the feature but doesn't work. Without acceptance criteria, there is no contract for success. The loop never closes.
The Fix: Every intent must have falsifiable success criteria. "The user can log in" is bad. "Entering valid credentials redirects to /dashboard" is good.
The Orphan
The Symptom: A spec that exists in isolation, disconnected from user pain.
Why it fails: You build the feature perfectly, but it solves the wrong problem. The "why" was lost three weeks ago in aSlack thread.
The Fix: Traceability. Every spec should link back to the specific friction point (support ticket, research clip) that spawned it. If you can't link it, don't build it.
The Black Box
The Symptom: A spec that defines inputs and outputs but ignores the system state.
Why it fails: The agent writes code that works in isolation but breaks the rest of the app. It introduces regression bugs because it didn't know about the existing auth provider or the legacy database schema.
The Fix:
Context injection. Your spec must explicitly declare the environmental constraints: "Must use existing Button component," "Must respect IsAdmin flag."
The Pathmode Standard
We built Pathmode to make these anti-patterns impossible.
- Structured Input: Required fields replace blank pages.
- Traceability: Friction is hard-linked to the spec.
- Verification Hooks: Success criteria are mandatory.
Stop writing prose. Start engineering intent.