Flesch–Kincaid Proofreader

Use the bundled script for measurement and sentence triage. Use the language model only for the semantic work a deterministic tool cannot do: preserving meaning, voice, and technical accuracy while rewriting.

Workflow

1. Choose the target grade. Use the user's target when given; otherwise grade 8.

2. Run the analyzer before editing:

   node scripts/readability.mjs --target 8 path/to/README.md

3. Review difficult sentences in descending grade order. Start with sentences that are both long and far above target. Listed complex words are candidates, not automatic errors.
4. Rewrite only where useful. Prefer:
   • one main idea per sentence;
   • familiar, precise words over longer synonyms;
   • active, concrete constructions;
   • bullets for genuine lists;
   • keeping required technical terms and explaining them once.
5. Re-run the same command. Continue until the copy meets the target or further simplification would harm accuracy, voice, or usefulness.
6. Report the before/after grade and any intentional exceptions. Never claim a passing score proves the copy is clear or correct.

Do not estimate the grade yourself, count words or syllables manually, or ask the model to rank every sentence. The script owns those deterministic steps.

Commands

Analyze one or more files:

node scripts/readability.mjs --target 8 README.md docs/getting-started.md

Analyze selected text through stdin:

printf '%s\n' 'Paste the copy here.' | node scripts/readability.mjs --target 8

Produce structured output for another tool:

node scripts/readability.mjs --json --target 8 README.md

Use as a check that exits with status 1 when any document is above target (or has no prose):

node scripts/readability.mjs --target 8 --fail-above README.md

Run node scripts/readability.mjs --help for all options. Markdown code blocks, link destinations, HTML tags, comments, headings, tables, and frontmatter are excluded by default. Inline code remains because it is often part of a technical sentence. Pass --include-code only when fenced code blocks should count as prose.

Interpretation

The script implements:

0.39 × (words / sentences) + 11.8 × (syllables / words) − 15.59

A result of 8.0 roughly indicates text suited to a US eighth-grade reader. Negative values are valid for very simple text. The test measures sentence length and estimated word length; it does not measure correctness, structure, jargon familiarity, accessibility, tone, or reader knowledge.

Syllable counting is a deterministic English heuristic, so names, acronyms, code identifiers, and specialist terms may be miscounted. Treat small score differences as noise. Keep accurate terms rather than gaming the score, and use judgment for text that is not English.

Validation

After changing the analyzer, run:

node --test tests/*.test.mjs