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, the spec stops being a "nice to have." It carries the product judgment an AI agent can't supply for itself — what to build, for whom, and on what evidence.

Yet most product requirements documents (PRDs) are broken. They suffer from one of these five anti-patterns.

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.

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 read like a checklist, not a blog post.

Why it fails: The agent can generate code that looks like the feature but doesn't work. Without acceptance criteria, there's no shared definition of 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.

Why it fails: You build the feature perfectly, but it solves the wrong problem. The "why" was lost three weeks ago in a Slack 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, label it an assumption and treat it as one until something backs it.

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

Pathmode is built to catch these anti-patterns before an agent builds, not to promise they can't happen.

• The preflight names the gaps. Six deterministic checks grade the title, objective, outcomes, constraints, edge cases, and verification, and the verdict names what is missing. A wishlist with no outcomes fails. So does a spec with no check concrete enough to run.
• Every claim shows what backs it. A claim reads Backed, Unreviewed, Assumption, or No evidence, so an orphan is visible as one.
• A person decides. The coding agent proposes the spec; the product manager answers its open choices and authorizes the exact revision before anything is built.

A failing verdict is not a wall. You can proceed with a named risk, but the risk is recorded, and the verdict stays failing until the gap is fixed.

Stop writing prose. Start engineering intent.