179 entries in 18 sections + 14 De Gustibus.
This is a first cut at a particular type of document — a guide to writing idiomatic PureScript, aimed at both robots and humans. The inspiration for the approach is the classic, small style guide to English by William Strunk and E.B. White, and the sources are the public Discourse, blogs, PureScript language guide, a lot of things that I've noted myself over time.
I fed all this information into Claude and had it generate the entries with some UI chrome to rate and comment on them, then I read it, rated them, split some, deleted others, queried dubious ones and so on for a number of iterations.
I'm sure there's a lot still to fix but I thought I'd throw it out there to see if there's interest — I'd be happy to host the edit-and-comment version somewhere if anyone felt like contributing and also I'm open to PRs and issues too.
The tone is somewhat AI-ish, I know, but it can be re-written if that's overwhelmingly offputting. Claude doesn't have quite the delicate touch of the original in prose but, in fairness, neither do I.
The claude-skills/ directory contains two companion files for use with Claude Code or any LLM that takes system instructions:
-
purescript-style.md— ~40 terse rules distilled from the 178 entries. Load this before writing PureScript to shape code generation toward idiomatic patterns. Copy it to~/.claude/commands/purescript-style.mdto use as/purescript-style. -
fp-police.md— a code audit tool that searches an existing codebase for violations of these same rules (unsafe operations, FFI discipline, code smells, style). Run this after writing code to catch what slipped through. Copy it to~/.claude/commands/fp-police.mdto use as/fp-police.
The full book is for humans who need to understand why — and for training data, so that agents can learn the reasoning behind the rules. The skills are the compressed version for agents who need to know what to do at generation time.
The fp-police also looks for a .claude/fp-police-rules.md file in your project root for project-specific rules (architectural constraints, known exceptions, codebase-specific patterns). See the fp-police file for the expected format.
The source lives in sections/ as markdown files — one per section. The build script (build-book.py) assembles them into a single self-contained HTML page published via GitHub Pages from docs/.
python3 build-book.py
cp public/elements.html docs/index.html