---
title: "Cadence: the proofreading tool I built because my brain is worst at proofreading"
url: "https://toddpaulbrownjr.com/writing/inside-cadence/"
author: "Todd Paul Brown Jr."
description: "A local proofreading app that reads Markdown aloud with synced highlighting. 368 tests, 2,995 segments rendered, zero failed. Built because dyslexia."
kind: "article"
updated: "2026-09-26T02:50:32+00:00"
---

# Cadence: the proofreading tool I built because my brain is worst at proofreading

I'm dyslexic. Proofreading my own writing is the exact task my brain is worst at — the eye skips, autocorrects, and fills in what it expects to see. So I built the tool that lets me do it with my ears.

[Cadence](/builds/cadence/) is a fully local, proofread-by-ear desktop app. It turns a folder of Markdown files into narration that highlights each paragraph as it's read, so I can catch what my eye misses. It runs entirely on my laptop: no account, no subscription, no cloud upload. Status: **shipped**, to an audience of one — it has never left my machine.

## The model is not the product

I asked Claude Code to get an open-source speech model running, expecting it to work out of the box. It didn't. The model itself worked fine, but a model alone isn't a product — there was no UI, no file handling, no audio caching, no way to track which paragraphs had changed in a revised manuscript.

So before any implementation, I wrote a 1,105-line prompt. Line nine said plainly: "Do not implement the application in this task." Instead, I asked for six deliverables: a repo audit, a product spec, architecture decisions, a phased roadmap, design requirements, and a handoff prompt for a separate design agent. All six exist.

The resulting design went through a 19-entry reconciliation ledger grading each proposed feature Essential, Beneficial or Decorative. About half were rejected. When a model "should just work" and doesn't, the missing piece usually isn't more model — it's the harness: a spec, decision records, and a design your own review can push back on. An agent will happily build that harness once you ask for it by name.

## How it works

The core is Electron with a Python/FastAPI sidecar. Documents parse into content-addressed blocks — unique IDs derived from the paragraph's content — so highlighting, notes, change detection and audio caching all line up on the same units.

When a manuscript is revised, only changed paragraphs re-render. Notes follow the text that moved, flagged for review rather than silently reattached when a match is uncertain. The diff-and-reconcile engine handles this: it compares the new parse against the cached one, identifies moved or edited paragraphs, and decides which audio segments to keep and which to regenerate.

That engine was the riskiest component, so I attacked it first. Three confirmed bugs, each fixed with a regression test, before it was declared safe to build on. The roadmap itself was built across three consecutive days in July 2026, with two later single-day sessions adding project management and a notes export.

## What broke

**A Windows quirk that failed silently.** A hidden file attribute on an entire project folder made every chapter show as stale and refuse to regenerate. The JSON writes kept succeeding, so the app looked fine while the audio never updated. The worker couldn't log the failure either. Both are fixed: the app now checks for hidden attributes at folder selection and the worker's error handling actually works.

**The diff engine's early bugs.** Moved paragraphs initially caused duplicate note attachments. Inserted paragraphs broke the sequence numbering. Deleted paragraphs left orphaned audio files. Each was caught in adversarial review, fixed with a test, and has stayed fixed.

## The numbers

- **368 backend tests** — 305 test functions expanded by parametrization (measured).
- **6.94 hours of narration** from a 63,000-word manuscript, produced in 98.2 minutes of GPU time, 1,869 segments, 0 failed (measured).
- **2,995 segments rendered** across two real projects — the manuscript and 51 company knowledge-base documents — 0 failed (measured).
- **51 of 51 documents** fully narrated, 2.51 hours of audio (measured).

Zero failed renders means the model itself was never the problem. The harness around it — parsing, caching, diff reconciliation, error handling — is what made it reliable enough to trust.

## What's next

Nothing urgent. The app does what I need it to do: I point it at a folder of Markdown files, it narrates them paragraph by paragraph with synchronized highlighting, and I catch errors my eye skips right over. It handles revisions cleanly, flags uncertain note relocations rather than guessing, and has rendered nearly 7 hours of audio across two real projects without a single segment failing.

I built it for myself, and it works. If it stays an audience of one, that's fine — it already solved the problem I had.

The full build details, architecture decisions, and test counts are on the [Cadence](/builds/cadence/) page. More verified numbers and receipts from other builds are on the [receipts](/receipts/) page.