How do I write a spec so a feature gets built right?
You can describe a feature, but specifying it so it gets built right eludes you. That gap is real and specific. A description lives in your head, where all the obvious things stay unsaid. A spec has to move the idea into someone else's head, and there the unsaid things go missing. What gets built wrong is almost always the part you thought was obvious. You knew what you meant, so you did not write it down, and the builder filled the gap with a different guess. Specifying well is mostly the discipline of writing down the things that feel too obvious to mention. Take your next feature and, after you describe it, hand the description to someone and ask them to tell you back what they would build. The places they guess differently are exactly the holes in your spec. Fill those, and the feature starts arriving the way you pictured it. The gaps are findable. You just have to look through someone else's eyes.