Or maybe, the takeaway is: revisit your work later, when it's no longer fresh in your mind :) You'll understand what the strengths and weaknesses of your new design are, and are better placed to make an improved iteration.
Incidentally, writers have been doing this for years with drafts and editing. We definitely need to do that with our APIs and designs (aka. more incremental refactoring).
> We definitely need to do that with our APIs and designs (aka. more incremental refactoring).
Not with APIs we've shipped. Then it becomes breaking changes that appear pointless to others. Even when it's logically worth it to go back and fix APIs, it's rarely worth it practically. If no one is using your APIs, then do whatever. If your APIs are popular, you might find yourself in "version next" limbo like so many major projects that redesigned and couldn't convince their users to follow.
You're absolutely right. FWIW, I think this iterative process should take place before publishing your API. Sometimes a design needs to 'sit' for a month or two and be used a bit before you realize its boundaries: what it does well, and what could be improved. If you're judicious about improvements (i.e. don't rewrite) you'll avoid the second-system effect and put out an API that'll be better than your first attempt. I realize that's not always possible.
Incidentally, writers have been doing this for years with drafts and editing. We definitely need to do that with our APIs and designs (aka. more incremental refactoring).