A Common Trap: Specifying Solutions, Not Problems

One failure mode is worth calling out on its own, because it's so easy to fall into. When you sit down to write a spec, the temptation is to describe the solution you've already pictured — "a sidebar with tabs," "a modal that pops up," "a Postgres table." But a spec full of solutions quietly locks in decisions you haven't earned yet.

Compare these two lines:

Bad:  Add a left sidebar with collapsible sections for each book status.
Good: Let me see my books grouped by status without losing the full list.

The first sentence has already chosen a sidebar, collapsible sections, and a layout — before anyone has confirmed those are the right calls. The second states the job to be done and leaves the AI (and you) free to find the simplest thing that satisfies it, which might just be three filter buttons. Describe the outcome you want; let the implementation stay negotiable for as long as possible. Solutions are cheap to change in a spec and expensive to change in code.