The Spec Interrogation: How AI Is Changing the Way Product Teams Write Requirements
James Mitchell
There’s a meeting that happens at nearly every startup, usually around the time the team hits fifteen people. An engineer asks a product manager, “Can you write up the spec for this?” The PM writes something. The engineer reads it and says, “This isn’t detailed enough.” The PM rewrites it. The engineer reads it again and says, “Now it’s too detailed.” The PM considers a career in landscaping.
Writing product specs is one of those things that everyone agrees is important and almost no one thinks is being done well. They’re either too vague to be useful or so exhaustive that no one reads them. They get outdated the moment the first design review happens. They live in Notion pages that haven’t been opened since Q3.
But something has shifted in the last eighteen months that changes the calculus significantly. Not because AI writes specs for you — it mostly doesn’t, at least not the parts that matter. But because AI has made a specific, underrated part of the spec-writing process dramatically better: the thinking part. The interrogation. The stress-testing. The “wait, what happens if the user does X” part that usually gets skipped when everyone’s rushing toward a sprint deadline.
This post is about how to actually use that.
Why Specs Fail (It’s Not What You Think)
Most people assume specs fail because of poor writing. They don’t. They fail because of poor thinking — specifically, thinking that stops too early.
A product manager under time pressure writes down what they know. They’ve had the conversations, they understand the rough shape of the feature, they write it out. What they almost never do — because it takes time, and time is the thing they don’t have — is systematically poke holes in their own thinking before handing it off.
Consider a simple feature: a user notification system. You write the spec. You describe what triggers a notification, what it says, where it shows up. You think you’re done.
You’ve probably forgotten:
- What happens when a user has notification preferences disabled at the OS level?
- What’s the behavior when the same event triggers multiple notifications in quick succession?
- How do notifications behave for users on degraded connections who receive them out of order?
- What’s the read/unread state persistence model across devices?
- How does this interact with your existing email digest feature?
None of these are edge cases in the pejorative sense — they’re cases. Users will hit them. Engineers will have to make decisions. The question is whether they make those decisions intentionally, from a spec, or ad hoc at 2pm on a Wednesday when a PR is up for review.
This is where AI earns its keep in the spec process.
The Interrogation Model
The most effective use of AI in spec writing isn’t “write me a spec.” It’s “find the holes in this spec.”
Here’s a workflow that actually works:
Step 1: Write the rough spec yourself. Don’t outsource the initial thinking to AI. You know the context, the constraints, the user research, the business goals. Write a rough draft — even a messy one. This doesn’t have to be formatted or polished. It just needs to capture your intent.
Step 2: Run it through an adversarial prompt. Paste your draft and ask something like:
“You’re a senior engineer about to implement this. What questions would you ask? What’s underspecified? What edge cases haven’t been addressed? What assumptions am I making that might not hold?”
This prompt — or variations of it — will surface twenty things you didn’t think about. Some will be irrelevant to your context. But usually at least five or six will be exactly the kind of thing that bites you in sprint review.
Step 3: Answer the questions. Actually answer them. This is the work. AI doesn’t do this for you — it just surfaces the questions. For each gap it identifies, you have to decide: do we handle this case? How? Does this change the core design? Do we explicitly out-of-scope it for now?
Step 4: Run it through a second lens. After you’ve addressed the engineering questions, run a different prompt:
“You’re a UX researcher who just ran usability tests on this. What would confused or frustrated users say? What are the most common points of failure in the user journey this describes?”
This catches a different class of problem. The engineering interrogation finds technical gaps. The UX interrogation finds assumption gaps — places where you’ve assumed user behavior that might not match reality.
Step 5: Clean it up. Now you have something worth formatting. Run a final pass to structure it — context, goals, non-goals, requirements, edge cases, open questions. This is the part where AI can help with the writing itself, though the substance should already be solid.
What Good Specs Actually Contain
There’s a structural question worth addressing: what should a spec include? The answer varies by team size and feature complexity, but the best specs I’ve seen consistently include a few things that most specs skip.
The “why not” section. Good specs explain not just what you’re building but what you explicitly decided not to build, and why. This is enormously valuable six months later when someone asks “why don’t we just add X?” — the answer is already written down. It also forces you to be honest with yourself about tradeoffs you’re making.
The success criteria that aren’t metrics. Everyone includes metrics. Fewer people include qualitative success criteria. “Users can complete the core flow without reading documentation” is a success criterion. “Support tickets about this feature should decrease” is a success criterion. These are often more useful than a conversion rate target when making implementation decisions.
The open questions section, with owners. Almost every spec has open questions. Most specs bury them or leave them implicit. Good specs surface them explicitly and assign an owner and a resolution deadline. “We need to decide whether to use optimistic UI here — Priya owns this by Thursday” is a sentence that prevents a Friday 4pm design debate.
The context someone joining the team in a year needs. This is the discipline most specs lack. Write as if someone who wasn’t in any of the planning meetings will read this cold. Why does this feature exist? What problem does it solve? What did the user research show? This context makes the spec useful as institutional knowledge, not just as implementation instructions.
The Format Trap
A quick note on format, because it causes real damage: the spec format wars are mostly a distraction.
Teams spend enormous energy debating whether specs should be in Notion or Linear, whether to use PRD templates or free-form documents, whether to include wireframes in the spec or link out to Figma. These questions matter less than everyone thinks.
What actually matters is that specs are findable, that they’re linked to the work they describe, and that they’re updated when the design changes. A great spec in a broken system (no links, no search, no culture of updating) is less useful than a mediocre spec in a system where everyone knows where to look.
Pick something. Use it consistently. Update it when things change. That’s it.
The one format argument worth having is about length. Specs that are too long don’t get read. A spec that doesn’t get read doesn’t exist. There’s a version of “thoroughness” that actually reduces spec quality because it buries the important things in noise. When in doubt, cut. The appendix is your friend.
Where AI Falls Short
The interrogation model works well. But it’s worth being honest about where AI adds noise rather than signal in spec writing.
AI doesn’t know your users. It can generate plausible-sounding user research findings, but they’re essentially hallucinations unless you’ve fed it actual data. When it says “users typically want X,” treat that as a hypothesis to validate, not a finding.
AI doesn’t know your tech debt. It can identify generic engineering edge cases, but it doesn’t know that your notification system shares infrastructure with your email service in a way that makes certain designs expensive. The interrogation surfaces questions; you have to answer them with knowledge AI doesn’t have.
AI doesn’t know your team dynamics. Sometimes specs fail not because of technical or UX gaps but because they’re written in a way that doesn’t account for how decisions get made on your team. That requires knowing your team.
AI makes specs sound finished before they’re done. This is subtle but real. AI writing tends to sound confident and polished. A spec that sounds done but isn’t done is dangerous — it creates false alignment. If you’re using AI to clean up prose, make sure the substance is actually solid before you run the polish pass.
A Practical Starting Template
Here’s the template structure I’d recommend for most mid-sized features. It’s not exhaustive — it’s meant to be a starting point you adapt:
Header
Feature name / Author / Date / Status / Reviewers
Context (2-3 paragraphs)
Why does this feature exist? What problem are we solving? What research or data is driving this?
Goals
Specific, concrete outcomes we’re trying to achieve. Keep this to 3-5 items.
Non-goals
What are we explicitly not solving? What’s in scope for a future version?
User stories
Concrete scenarios with specific user types. “As a new user who hasn’t set up integrations yet, I want to…” is better than “As a user, I want to…”
Requirements
Split into must-have and nice-to-have. Keep must-haves ruthlessly small.
Edge cases and error states
The things that happen when the happy path isn’t taken. This section should be generated through the interrogation process above.
Success criteria
How will we know this worked? Include both quantitative (metrics) and qualitative criteria.
Open questions
Outstanding decisions, with owners and deadlines.
Appendix
Wireframes, research links, relevant Slack threads, anything that provides context without cluttering the main doc.
The Spec as Communication Artifact
There’s a perspective shift that makes all of this easier: stop thinking of the spec as documentation and start thinking of it as a communication artifact.
Documentation describes what was built. A spec is trying to achieve alignment before building happens. That framing changes what you prioritize.
If you think of it as documentation, you optimize for completeness. If you think of it as communication, you optimize for clarity and shared understanding. You write for a specific audience — the engineer who’s going to implement it, the designer who’s going to build the flows, the stakeholder who approved the roadmap item. You ask yourself: after reading this, will they know what to build? Will they be able to make good decisions when reality diverges from plan?
The best product specs I’ve read feel less like technical documents and more like a good brief — they give you enough to go deep, and they make the intent so clear that the right decision in an ambiguous situation becomes obvious.
That’s hard to achieve. But it’s the right target to aim for. And it’s one of the few places where the combination of human judgment and AI interrogation can genuinely close the gap between what gets written and what gets built.
Want to see how high-performing product teams structure their spec workflows? ProductOS includes spec templates, review checklists, and AI-assisted gap analysis built into the product workflow — so the interrogation process happens before the work starts, not after.