The "finally got it working then realized Spotlight already does this" moment is brutal.

API design isn't just about functionality. it is about discoverability and if your right-click menu uses different models than your API and your error messages don't explain why, you are just creating friction for no reason.

Sometimes the "proper" solution isn't worth the super complicated maze.