The plague file

The prose diseases of this repo: what they look like, why they hurt, how to rewrite them, how to grade them. Built the way the doctor doesn’t catch the fever says to build a taxonomy — by diagnosing a real batch of writing, not from theory. Every disease below has a specimen that actually appeared in this repo; specimens marked (fixed) were rewritten after diagnosis, and the sick version is preserved here as the reference.

The healthy register, for calibration: a reader who was not in the work sessions understands every sentence on first pass. A single controlled metaphor that gets stated literally somewhere in the page is house style, not disease — “the owner is the mint,” “the doctor doesn’t catch the fever.” The diseases start where density or reference outruns the reader.

Two diseases have full notes of their own and are only pointed to here: compression (labels that resolve only in the writer’s context) and notes that rot (pointers to the work-session that mean nothing later).

1. Overloaded sentence

Symptom: one sentence doing three jobs — claim, mechanism, and judgment — chained across colons, semicolons, and em-dashes. Usually 40+ words, three or more dependent clauses. You re-read it to find the subject.

Specimen (fixed): “What the incidents do establish is structural, and it holds at any rate: an ownership requirement nobody declares is one no gate can check, and a lane’s context cannot contain its siblings — so whenever the assumption is wrong, the suite stays green anyway, silently conditioned on the world being quiet, and the bill arrives later as machine-load-dependent flakiness, the least attributable symptom there is.”

Why it hurts: the reader can’t hold five clauses at once, and the load-bearing claim gets buried under its own mechanism and commentary.

Remedy: one idea per sentence. Claim, then mechanism, then consequence, as separate plain sentences.

Grading: bad = 40+ words, three jobs, needs a re-read. moderate = two jobs and one nesting level. mild = long but linear on first pass.

2. Grandiose flourish

Symptom: a superlative or compressed compound tacked onto a sentence’s end, performing importance instead of adding information.

Specimen (fixed): “…machine-load-dependent flakiness, the least attributable symptom there is.”

Why it hurts: the reader decodes a flourish and a compound noun and gains nothing over “flakiness that’s very hard to trace.”

Remedy: cut the superlative; unpack the compound into ordinary words.

Grading: bad = flourish and compressed compound in one clause. moderate = one dramatic flourish where a plain word exists. mild = dressy diction that still reads clearly.

3. Phrase overrun

Symptom: a coined phrase repeated verbatim across a page. The first use lands; the repeats read as the writing admiring itself.

Specimen (fixed): “silently conditioned on the world being quiet,” coined in a claim paragraph and repeated verbatim two sections later.

Why it hurts: the reader starts noticing the phrase instead of the point.

Remedy: keep the strongest occurrence; state the others plainly. Do not flag a page’s declared central metaphor — deliberate restatement of “the log is the ledger” is structure, not overrun.

Grading: bad = coined phrase three or more times. moderate = the same coined phrase verbatim twice. mild = an echoed ordinary phrase.

4. Compression

Symptom: a label or dressy abstraction whose referent lives in another note or in the writer’s head — the reader can’t cash it out without leaving the page. The full mechanism is its own note.

Specimen (fixed): “reports that substitution in the grammar of verification”; also “the way the killing hypothesis usually is,” resolvable only through a cross-link.

Why it hurts: a label is a pointer into the writer’s map; the reader doesn’t have the map.

Remedy: say the plain thing on first use, then link. Coin only after the coin has been cashed out on the page.

Grading: bad = coined label, no in-note resolution, no link. moderate = resolves only via a link the reader must follow. mild = resolves within a sentence or two.

Watch list

Aphorism stacking — “X is Y, not Z” constructions chained until they stop informing. One infestation was diagnosed and rewritten (the before/after is commit cdfecc4); no live specimen remains, so it sits here as a watch item rather than an instanced disease. One aphorism per page earns its place; a chain of them is register, not thought.