Readability Skill

---
name: readability-analysis
description: Measure and improve the readability of prose or Markdown using objective metrics (Flesch Reading Ease, Flesch-Kincaid grade, Gunning Fog, SMOG) and per-sentence flagging. Use this whenever judging whether writing is clear or accessible, checking a document's reading level or grade level, deciding if a sentence or paragraph is too dense or hard to read, before finalizing a report/policy/SOP/email/article, or any time the user questions readability or asks for something to be made "more readable", "simpler", or "clearer" - do not eyeball readability, run this skill and cite the numbers.
---

# Readability Analysis

Judging readability by feel is unreliable and easy to argue with. This skill replaces
opinion with measured scores and pinpoints the specific sentences that drag a document
down, so edits are targeted rather than vibes-based.

## When to use

- The user questions whether something is readable, clear, or accessible.
- The user asks to make text "more readable", "simpler", "plainer", or "clearer".
- Before finalizing any prose deliverable (report, policy, SOP, article, email).
- To compare a draft against a rewrite and prove the rewrite is better.
- To pick the worst sentences in a long document to rewrite first.

## What it measures

Formula metrics, computed with `textstat` (consistent syllable/complex-word counts,
not estimates): Flesch Reading Ease, Flesch-Kincaid grade, Gunning Fog, SMOG, plus
Dale-Chall (word-familiarity based, catches jargon syllable counts miss), Coleman-Liau
and Automated Readability Index (character-based), and Linsear Write (tuned for
technical manuals). A consensus grade (text_standard) summarizes them all, and the
difficult-word count/list names the actual unfamiliar words. Plus structural stats:
words, sentences, words/sentence, syllables/word. See `references/thresholds.md` for
formulas, interpretation bands, and source links.

Flagged sentences also carry grammar notes from a spaCy dependency parse
(en_core_web_sm): passive voice, nominalizations (verb-derived nouns to rewrite as
verbs), and clause nesting depth 3 or more. The notes name the fault, so a rewrite
knows what to fix; the scores only say a threshold was exceeded. A document-level
count of passive sentences is also reported.

The script strips Markdown (fenced and inline code, tables, links, headings, list
markers, bare URLs) before measuring, and terminates list items so a bulleted list is
not scored as one giant run-on sentence. Inline code spans are neutralized: a plain
word in code font (`` `signed` ``) stays, but an identifier or path
(`` `patient_data_export` ``, `` `evidence_summary.py` ``) counts as one generic noun
instead of one enormous polysyllabic "word" that inflates the grade. This matters:
scoring a Markdown table, a list of URLs, or code identifiers as prose yields garbage.
Use `--raw` only for genuine plain text.

For text pulled from Jira (or any raw Jira wiki markup -- `{code}` / `{noformat}` blocks,
`{{monospace}}`, `hN.` headings, `[text|url]` links, `{color}`/`{panel}` macros, `\\`
breaks), add `--jira`: it neutralizes that markup before the Markdown pass so identifier-
and macro-heavy issue text measures as prose, not syntax. Text fetched from the Jira API
as Markdown already benefits from the default inline-code and list handling; `--jira`
additionally covers native wiki markup.

## How to run

The script is standalone (dependencies declared inline) and runs with uv:

```bash
uv run scripts/analyze_readability.py <file.md>
```

Useful options:

- `--max-words-per-sentence N` (default 25), `--max-grade N` (default 14),
  `--max-fog N` (default 14): tighten or loosen the sentence-flagging thresholds.
- `--jira`: pre-process raw Jira wiki markup before the Markdown pass.
- `--json`: machine-readable output for further processing.
- `--raw`: skip Markdown stripping (plain text input).

Analyze stdin by passing `-` as the path.

## How to interpret and act

1. Read the document-level metrics. A Flesch Reading Ease near or below 0, or a grade
   far above the audience level, signals a problem. For technical or regulatory prose,
   target roughly grade 10-12 / Fog ~12 / Reading Ease 40-50; do not expect the 60-70
   "general public" band, because domain vocabulary sets a floor.

2. Work the flagged-sentence list, worst first. Each flag shows word count and per-
   sentence grade/fog. The usual cause is one sentence doing too much.

3. Fix structurally, not by dumbing down vocabulary. The grammar notes point at the
   specific fault:
   - one idea per sentence; split compound sentences;
   - unnest parentheticals (a parenthetical inside a parenthetical is a rewrite signal);
   - convert inline "(a)/(b)/(c)" or semicolon-chained runs into a bulleted list;
   - "passive voice" -> rewrite active, naming the actor;
   - "nominalizations" -> rewrite the noun as its verb ("make a determination" ->
     "determine"), after checking the word is genuinely verb-derived;
   - "N nested clauses" -> split or unnest;
   - keep necessary domain terms - the goal is clearer structure, not simpler concepts.
     The difficult-word list shows which terms a reader is least likely to know, so
     define those rather than deleting them.

4. Re-run the script on the rewrite and report before/after numbers. State the metric
   and its source rather than asserting the text "reads better".

## Reporting format

When presenting results, lead with a compact before/after table of the metrics, then
the rewritten text. Always name the metric and cite `references/thresholds.md` (or its
linked sources) so the judgment is verifiable, not subjective.