This shows how difficult it is to get the design of an interface right without writing the application for which it is intended at the same time. I am reminded of it all the time myself, no matter how well I think I know the problem domain or how much I plan ahead.
The kernel policy of not allowing experimental syscalls but demanding indefinite support even for failed attempts once they are in a released kernel may have made it harder to co-develop application and interface. Maybe a policy demanding credible proof-of-concept user-space code accompanying any new syscall would do? (And, as has been suggested before, a man page.)