Feature Specification Document

The Feature Spec Is Where Good Ideas Go to Get Real

Stripe's engineering culture has a saying: "If you can't spec it, you can't ship it." Their PMs write feature specifications so detailed that an engineer who's never seen the codebase could build from them. Not because engineers need hand-holding — because ambiguity is the silent killer of shipping velocity.

Most product teams skip this step. They have a PRD that says "users should be able to filter search results" and assume engineering will figure out the rest. Then two weeks later, someone asks: "What happens if the user applies twelve filters at once?" and nobody knows.

The Missing Layer Between Strategy and Code

A 2022 McKinsey study on software development productivity found that unclear requirements are the single largest source of rework in engineering teams, accounting for up to 35% of wasted development time. Not technical debt. Not poor tooling. Ambiguity.

The PRD sits at the strategy layer — it defines the why, the who, and the what at a high level. But there's a gap between "we're building a collaborative editing feature" and the actual implementation. That gap is where feature specs live. They answer the uncomfortable questions: What's the data model? How do error states render? What's the API contract? What are the edge cases when two users edit the same paragraph simultaneously?

This is the document that prevents the "oh, we didn't think about that" moments in code review. Teresa Torres calls this the "opportunity space" problem — teams are great at identifying opportunities but terrible at specifying them precisely enough to build.

How This Prompt Helps

This prompt generates a build-ready feature specification from your feature context. You provide the feature name, parent PRD, target release, and engineering lead — and it produces user flows, edge case documentation, API contracts, error states, acceptance criteria, and testing considerations.

It's particularly useful because it asks the questions you'd forget to ask. Every experienced PM has shipped something and then realized they never specified what happens when the user has no internet connection, or what the empty state looks like, or how the feature degrades for users on older browsers.

When to Reach for This

• You've finished a PRD and need to break it down into engineering-ready specifications for individual features
• An engineer asks "what should happen when..." and you realize the answer isn't written down anywhere
• You're working with a distributed team across time zones and need specs that stand alone without a meeting
• A feature has complex state management or multiple user paths that need to be documented before coding starts
• You want to reduce code review back-and-forth by defining acceptance criteria upfront

What Good Looks Like

A strong feature spec reads like a contract between product and engineering. It has user flows with decision trees, not just happy paths. Error states are specified with exact copy and behavior. API contracts include request/response schemas. Acceptance criteria are testable — an engineer or QA can read them and say definitively "yes, this passes" or "no, this doesn't."

Sources

• The Real Cost of Unclear Requirements — McKinsey Digital
• Continuous Discovery Habits — Teresa Torres