One word can wipe out a paragraph

Read this sentence: "Wind up the clock before the wind picks up."

You probably didn't notice anything. Two spellings, two sounds, two meanings, and your brain sorted it out before you got to the period. For a lot of dyslexic readers it does not work that way. The first "wind" gets read one way, the second one arrives looking identical, and the sentence has to be rebuilt from scratch. Sometimes the paragraph goes with it.

That is a different problem from the one most people picture when they hear dyslexia. It's not letters swimming on the page. It's specific words, and the same words every time.

So I built something for it. It's called dyslexic-rewrite, it's free, it's MIT licensed, and it runs on your own computer with no account and nothing sent to a server. The reading test that goes with it is at unwindwords.com.

What it does

You hand it a text file, a chapter, a whole EPUB. It reads through and flags what is likely to trip a reader: a word with two pronunciations, a word used twice nearby with two different meanings, a phrasal verb whose parts mislead ("wind up" means "end up," not anything to do with winding), sound-alike pairs that land close together (from and form, quiet and quite), rare words, long words, and sentences with too many clauses stacked inside each other.

Then it fixes what is safe to fix and leaves the rest alone with a hint. "Wind up the clock" stays, because it's literal. "We'll wind up in Omaha" becomes "We'll end up in Omaha." A long sentence with a clause wedged between the subject and the verb gets split into two. Names, numbers, quotes, and URLs are locked; a rewrite that changes one of those is a bug, not a feature.

Every change is reversible. Open the output in a browser and the changed words are underlined; hover and you see the original and why it was swapped. Flagged-but-kept words get a dotted line and a pronunciation cue. That design choice isn't mine. In 2013 Luz Rello's group tested automatic synonym replacement on dyslexic readers and it didn't help. Showing an easier word on demand did. So the original never leaves the page.

Three layers

The general rules work for anyone. Underneath that there are profiles that shift the weights: phonological, visual, attention. A reader whose problem is working memory gets more sentence splitting; a reader whose problem is decoding gets more attention on word choice.

The third layer is the one I care about most. dysrewrite learn reads the reader's own writing, their emails, their notes, a transcript of them talking, and builds a profile from it: how long their sentences run, how they join clauses, which words they use without thinking. A word that shows up in your own messages is never "rare" for you, whatever the frequency tables say. The tool rewrites toward how you already think.

When a word trips you in the reader view, you tap it. That goes back into the profile.

The part I didn't expect

I went looking for the research on heteronyms and dyslexia, expecting to find a stack of papers. There aren't any. Nobody has directly studied whether a spelling with two readings stalls a dyslexic reader more than it stalls anyone else. There's adjacent evidence about garden-path sentences and working memory, enough to make it a reasonable hypothesis. It's not a finding.

That changed what the project is. It's not just a rewriter anymore; it's a way to collect the data nobody has.

That's why the website exists. unwindwords.com runs the same engine and adds a two-minute A/B test: two matched passages, one original and one rewritten with your profile, timed, five comprehension questions each, and a "tap the word that tripped you" step. The passages were written for this, in pairs, with the trigger words planted on purpose so the original and the rewrite actually differ. Sign-in is an emailed code, no password. Results feed your profile, and if you opt in, they feed the project.

If it turns out the rewriter helps, there will be numbers that say so. If it doesn't, there will be numbers that say that too, and I'd rather know.

How it's built

Python, spaCy for the parsing, a curated table of a hundred or so heteronyms with part-of-speech-keyed alternatives, wordfreq for the rare-word detector, Metaphone for sound-alikes. The rewriter is deterministic rules by default. There's an optional LLM engine that sends each paragraph with its trigger list to any OpenAI-compatible endpoint, Ollama on your laptop by default, and every paragraph the model returns is checked: names, numbers, and quotes must come back verbatim and the length has to stay in range, or that paragraph falls back to the rules. I costed the cheapest hosted option at about ten cents per 90,000-word book. The end state is a small fine-tuned model trained on the pairs readers accept, which brings the marginal cost back to zero.

The site is FastAPI and Postgres on the back, React and TypeScript on the front, deployed to Fly from GitHub Actions. Same shape as the last thing I shipped, because it works.

What I need

Readers. If you or someone you love has dyslexia and is willing to spend two minutes on unwindwords.com, that's worth more than any pull request. If you want to contribute code, the easiest wins are more heteronyms in the table, a language pack (Spanish first; that's where most of the research is), or a failing test for a sentence the rules mangle.

I started this because of one reader and one word. I'd like to find out how many others there are.