I'm (temporarily stalled) in the middle of writing a CLI manpage for roughly this kind of purpose (finding a public interface that makes me happy before finally

I'm (temporarily stalled) in the middle of writing a CLI manpage for roughly this kind of purpose (finding a public interface that makes me happy before finally cutting the first release). It has been clarifying in some big ways, but I also feel like I wouldn't have been able to do this without an initial implementation that I and one or two others have been putting through the paces. It's taken some time to use it in enough real-world cases that I feel like we've actually discovered a significant fraction of the features it needs. It takes reflecting on each feature for long enough to understand if it is global or situational, to decide if it's just a change to the program, a new default you can disable, or a new optional feature you must enable. Or is it really a fellow traveller with a number of related features that signal the need for a new mode? Finding an interface that doesn't annoy me has taken collecting the entire current feature list, the next several planned features, and some "I suspect someone will ask for this some day" sorts of things--and then stepping far enough back from them to distill a smaller number of verbs they can be grouped under.