Rick Hull (Jan 15 2026 at 18:48): Rick Hull (Jan 15 2026 at 18:48):I like the LLM-friendly tutorial and stdlib docs, but I (claude) was able to condense the tutorial to .txt to 11KB from 87KB. this is much more token efficient. this involved removing some fluff from the tutorial. i think we could have a .txt or .md representation of stdlib that is much condensed from the current version. i am writing a script to do this and cache the result locally. but should there be a simpler version on the website?
Rick Hull (Jan 15 2026 at 18:59):oh, it looks like there is already a compact form for stdlib. i notice that my Claude Opus (with Z.AI model) struggled mightily to reach the doc, due to the redirect. its webreader tool worked, but its attempts with curl and python failed until I did the troubleshooting
Rick Hull (Jan 15 2026 at 19:10):if the tutorial happens to be authored in .md (no idea on the CMS), then making this file available to the LLM should be better than the tag soup currently provided
Steve Howell (Jan 15 2026 at 21:28):Speaking of the tutorial, is it possible for an AI to write all the tutorial examples to a repo of simple programs to examine? I've been through the tutorial, and it's excellent. But after going through the tutorial, I think it would be helpful for me to work with a simple repo of tutorials that I could clone and modify.
Luke Boswell (Jan 15 2026 at 21:31):We have all the examples in https://roc-lang.org/examples/ but they are a WIP migrating across to the new compiler, also we have an exercism track.
Luke Boswell (Jan 15 2026 at 21:34):Before we can really migrate the examples we need to finish migrating the platforms like basic-cli. The platforms are fairly large and I've been slow rolling it and fixing all the compiler bugs I find along the way. Also there is some work to "translate" into the new syntax, now we have static dispatch etc we can write nicer API's.
Steve Howell (Jan 15 2026 at 21:34):Oh, that's perfect for me now! Thanks for the link.
Luke Boswell (Jan 15 2026 at 21:35):If anyone is interested in assisting, every little bit helps... the WIP branch is over at https://github.com/roc-lang/basic-cli/tree/migrate-zig-compiler
Steve Howell (Jan 15 2026 at 21:36):This is genius: https://roc-lang.org/examples/AllSyntax/README
Luke Boswell (Jan 15 2026 at 21:36):It's at the point now where what is there is working nicely across all the supported targets, and we have CI in place. Now it's going through each module and thinking about the API.
Luke Boswell (Jan 15 2026 at 21:37):Steve Howell said:
This is genius: https://roc-lang.org/examples/AllSyntax/README
Yeah it's great. Here is a version for the new compiler and syntax in case your interested https://github.com/lukewilliamboswell/roc-platform-template-zig/blob/main/examples/all_roc_syntax.roc
@Anton has done a lot of work building that.
nandi (Jan 15 2026 at 22:45):I made an mcp using that syntax file, but what i've been using recently is creating a roc syntax skill that uses that file
Rick Hull (Jan 16 2026 at 01:02):@Luke Boswell I have been looking at basic-cli but it's too early for me to get involved. i also skimmed your platform templates. Once I get the C version of my platform working with the rust compiler, I may start over with a zig template on the new compiler
Luke Boswell (Jan 16 2026 at 01:03):Have you seen the C template? https://github.com/lukewilliamboswell/roc-platform-template-c
Rick Hull (Jan 16 2026 at 01:03):@nandi I have a condensed 11 KB roc-tutorial.txt, and a local copy of the stdlib LLM stuff, which I split into the compact file (23 kb) and the full file. this is to be efficient with tokens. but I haven't done anything with claude skills yet. any advice?
Luke Boswell (Jan 16 2026 at 01:03):That's using the old compiler still... I need to update that also
Rick Hull (Jan 16 2026 at 01:04):Luke, no -- maybe i should start there. i have been struggling! looking at lib.rs has been helpful
nandi (Jan 16 2026 at 01:05):i don't use claude i use factory droid I usually just say "create a skill that uses this file to syntax check roc code" and then when i am doing edits i mention somewhere in context to use the skill
Rick Hull (Jan 16 2026 at 01:09):interesting! that's new for me. I've been using claude / gemini / codex, but lately been using the claude frontend with Z.ai models and API calls (they implement the anthropic api). I got a monthly subscription for $28 that lasts a year ($6 / month after year 1). it has like 5x the usage limits of claude pro ($20 / month). i found that its opus-model burned through context, but that might have been my fault, as my prompts made it try to ingest large docs
nandi (Jan 16 2026 at 01:11):Im a fan of z.ai too, glm4.7 is pretty good. using it with cerebras is crazy fast, kinda expensive tho, might get a subscription when they have availability
Rick Hull (Jan 16 2026 at 01:14):the subscription has worked well for me, but i'm not like a power user. i'm just on the Lite plan.
nandi (Jan 16 2026 at 01:14):Im talking about $50/month cerebras subscription
Anton (Jan 16 2026 at 10:10):Luke Boswell said:
If anyone is interested in assisting, every little bit helps... the WIP branch is over at https://github.com/roc-lang/basic-cli/tree/migrate-zig-compiler
Personally I would not recommend that new people help with this branch, this requires deep familiarity with platforms. I will get back to this branch once I'm done with the benchmarks and https://github.com/roc-lang/roc/pull/8967
Anton (Jan 16 2026 at 10:12):Rick Hull said:
if the tutorial happens to be authored in .md (no idea on the CMS), then making this file available to the LLM should be better than the tag soup currently provided
We have it available here: https://roc-lang.org/llms.txt
Only in a relatively small part at the beginning does it use a lot of HTML tags.
Anton (Jan 16 2026 at 10:23):I also made issue #9039 for additional improvements to the AI docs.
Rick Hull (Jan 16 2026 at 14:41):Thanks Anton, I added some comments to the GH issue and PR :)
Rick Hull (Jan 18 2026 at 15:02):I've had some struggles getting my LLMs to use the new compiler features and stop using old structures. even after feeding Builtins.roc and all_syntax_test.roc with fresh context, they still try to match on Bool.true (rather than True). so I got the LLM to write its own tutorial with some gotchas and additional explanation of confusing areas.
UPDATE: see later comments for the most recent version
Rick Hull (Jan 18 2026 at 16:27):I created a condensed tutorial, going from 22KB over 1k lines to 8KB over 400 lines.
UPDATE: see later comments for the most recent version
Rick Hull (Jan 18 2026 at 16:52):I generated the condensed tutorial in order to populate a SKILL.md for claude code. The current version has a "cursed line" though:
Functions with side effects are marked with
!and use=>:
When the skill is loaded:
Error: Bash command permission check failed for pattern "!
and use": This command requires approval
I suspect this is unique to claude code, and I changed the wording in my SKILL.md but not the gist above or its source. just FYI
UPDATE: this is a known issue with the overly aggressive bash-exploit parser in claude code. a major pattern to avoid is: backtick-bang-backtick: ! presumably this will be fixed at some point
Functions with side effects are marked with bang (!) and use
=>:
Richard Feldman (Jan 18 2026 at 17:32):yeah we can just tweak the wording on that one since it's llm-specific anyway
Richard Feldman (Jan 18 2026 at 17:32):to not use backticks
Richard Feldman (Jan 18 2026 at 17:32):docs for human readers get the markdown converted to html anyway :smile:
Rick Hull (Jan 18 2026 at 17:38):How do opaque types (or the new analogy) work in the new compiler? My LLM can't find anything in Builtin.roc or all_syntax_test.roc
What I am trying to do with opaque types is wrap List(U8) for a couple different specific needs: 32-byte sk, 32-byte pk, 64-byte sig
Richard Feldman (Jan 18 2026 at 17:41):so we now have:
Bool : [True, False] - type alias, meaning you can find/replace all instances of Bool with [True, False] and nothing would change whatsoeverBool := [True, False] - nominal type, meaning if you also define Foo := [True, False], you can't use Foo and Bool interchangeably even though they hold the same informationBool :: [True, False] - opaque type, meaning it's nominal and also you can only see or use its contents (so, the [True, False] union) in the same module where it's defined Rick Hull (Jan 18 2026 at 18:05):LLM generated condensed tutorial for new compiler, with additional type info from Richard: https://gist.github.com/rickhull/db2cf4be0a31488e15080c8e8a2a7252
This supersedes any of my gists above; I am going to remove those links.
Rick Hull (Jan 18 2026 at 18:50):Here is my current claude skill, focused on roc-nightly. The intent is to keep it to minimal token usage.
There are 4 referenced docs, withROC_TUTORIAL_CONDENSED.md using the @ syntax to attempt to force claude to read it at skill activation time. https://gist.github.com/rickhull/793aa5755e8227fe7c62645bf08b45cb
UPDATE: gist updated and simplified as of 2pm eastern
Rick Hull (Jan 18 2026 at 19:30):Here is LLM generated documentation for type wrappers: https://gist.github.com/rickhull/1b524fd675e9a2a1b7bf551b70e7ec9a
This understanding was the result of a lot of exploratory testing by the LLM using its claude skill. The current claude skill used a lot of churn and tokens to get to this point.
Please let me know if you see anything wrong
Richard Feldman (Jan 18 2026 at 19:57):sorry, this is so wrong it'll be easier for me to just write the relevant sections of the language reference. :sweat_smile:
Richard Feldman (Jan 18 2026 at 19:58):I don't want to spend time trying to fix this...I have never seen the current generation of models generate usable documentation, and this unfortunately reinforces that for me.
Rick Hull (Jan 18 2026 at 20:15):ok, good to know! my intent here is not to crowdsource fixes or anything like that. this is mostly a learning exercise for me, and I don't know of better sources. are there better references that I should be using (e.g. per the current claude skill)
Rick Hull (Jan 18 2026 at 21:53):ok, now I'm looking at roc-lang/roc/langref is this a good resource for the new compiler? Opus says: yes
Rick Hull (Jan 19 2026 at 04:40):I did a big LLM run (Z.ai's Opus) against roc-lang/roc ignoring crates/ and focusing on src/ and langref/.
Here is a comprehensive LLM-generated roc-nightly tutorial:
https://gist.github.com/rickhull/ad9a8ca20adf332242524d3b1db01e68
Anton (Jan 19 2026 at 13:22):I've had some struggles getting my LLMs to use the new compiler features and stop using old structures.
I usually tell Claude that it does not have the new Roc syntax in it's training data and it needs to pay close attention to the examples I gave it.
Rick Hull (Jan 19 2026 at 13:25):mine loves List.pad :crying_cat: i am going to make a specific GOTCHAS.md that the skill will eager load
Last updated: Feb 20 2026 at 12:27 UTC