The problem
Feature specs are best started at a whiteboard. You can sketch the user flow end to end, draw the state machine, mark the edge cases, and diagram how the feature interacts with existing systems — all in the same visual space. The engineers in the room can point at the board and say 'what happens here?' and the answer gets added immediately.
Then someone has to write the actual spec document. That person usually wasn't drawing — they were talking. The spec ends up as a linear document that can't capture the visual relationships between states. The edge cases that were explicitly circled on the board don't make it in. Engineers implement the happy path; the edge cases stay on the whiteboard that's been erased.
Skipping the whiteboard and going straight to writing doesn't help. A feature spec written in isolation, without the spatial exploration a whiteboard enables, is usually missing the hard questions. The whiteboard is where you find the edge cases before they find you in production.