[derdi]

Just in case the above is not considered constructive enough, how about this: In my experience, with some prompting and iterations, AIs do reasonably well at writing solid, "boring" code. They do really badly at writing useful documentation, and this is a major pain point when reviewing their output. A system that claims to be oriented towards human review must address this somehow. It must talk about how it addresses it, and it must demonstrate that its own documentation is significantly better than unfiltered LLM output.

This system does not demonstrate this. It needs clear guidelines: Start with the big picture. Show an example. Show comments in that example. Don't get bogged down in the details of the internal workings of the compiler. Don't use jargon like "kernel" to mean "lowered intermediate representation". Don't use "carrier" when you mean "file". It's just a file, FFS. But again, don't tell me at all about the fact that there is an intermediate representation; that's not "big picture", and anyone who cares about compiler internals will already have guessed that you have an intermediate representation. Do tell me about the effect system in the first two paragraphs! That seems to be what sets this language apart. Do give me a brief argument why an effect system is a good match for a system where humans don't have to type everything by hand. And so on and so forth.

[zparky]

I always feel like I'm losing my mind when reading LLM comments or prose for code. It's so esoteric and 'i-am-very-smart' and makes me feel like I'm not supposed to read the comments in the first place

[derdi]

Once, during an especially tedious review session, I told my agent something like "comments are not meant to demonstrate how well you understand the system, they are meant to help others understand the system". It felt like that helped.

[zparky]

that sounds like a good idea to try, thanks!