Yes, I have had the same experience with the specification. It really is quite difficult to follow :c
Their SpecTec system is fancy and neat but I don't think that auto-generated specifications produce something worth reading. Perhaps in the future when there's less churn, there might be a hand-written specification? In the mean time I've needed to jump into their Discord to ask clarification questions about the high-level stuff. Once understanding that and the grammar conventions and the like, the specification becomes much more readable, though still not great.
Certainly nothing like an RFC. But maybe I have too high standards...
(It doesn't help that the syntax is *weird*. You've got your choice of an S-expression Scheme syntax or a stack-oriented ML syntax, *and* you can use both together. And there's at least one undocumented de facto syntax floating around AFAIK, though I believe the standard merged support for the main features it was used for, so hopefully test suites and the like will switch away from it at some point.)
Their SpecTec system is fancy and neat but I don't think that auto-generated specifications produce something worth reading. Perhaps in the future when there's less churn, there might be a hand-written specification? In the mean time I've needed to jump into their Discord to ask clarification questions about the high-level stuff. Once understanding that and the grammar conventions and the like, the specification becomes much more readable, though still not great.
Certainly nothing like an RFC. But maybe I have too high standards...