Write Prose Fix

Reword until the prose lint passes, and change nothing else

Reword one file until its linters report nothing. Someone has already decided what the document says, and that part stays fixed. Change how it reads, and only as far as the findings require.

Context

!bash ${CLAUDE_SKILL_DIR}/scripts/context.sh $ARGUMENTS

The one rule

Leave the meaning alone. Every claim the document makes survives your pass intact, and so does every number, path, identifier, and name in it.

A finding you can only clear by saying something different is a finding you leave alone. Report it instead. Inventing a claim to please a linter is the worst outcome available here, because it reads as clean and puts words into the document that nobody wrote.

Reword. Don't rewrite.

Your inputs

$ARGUMENTS carries the target first, then the command that judges it. Anything after a -- is what the caller wants addressed, which on a second pass is the findings review-prose-fix returned. Treat those as the work: resolve each and say so.

The context below already ran the command and printed the document, so the findings and the text are both in front of you. Don't re-run the command to see them again.

The loop

1. Read the findings in the preceding context. Count them.
2. Fix the whole list in one editing pass, cheapest findings first, editing only the target.
3. Run the lint command again. Compare the count.

Never re-run after one edit. Each round costs the same whether it clears one finding or twelve, and the session behind this skill spent half its Bash calls on linters it re-ran a fix at a time.

Stop at any of these:

• The command prints nothing, having printed something earlier. Read the next section before you trust that.
• The count fails to drop across two runs in a row.
• A finding you already cleared comes back. Something you wrote to clear one rule is tripping another, and a third pass at the same pair rarely helps.
• The loop has run five times.

The session this skill exists for spent thirty-one rounds on one commit message. Stopping early costs the caller a short unresolved list, and continuing costs them the context this skill exists to save.

Silence proves nothing on its own

A checker that never ran and a document with nothing wrong print exactly the same thing.

Vale matches a path against the sections in .vale.ini, and the match is exact. A path that no section names doesn't load any styles, so vale reads the file and applies nothing to it. Vale then prints nothing and exits zero. Measured against this repository, one paragraph of deliberately bad prose draws 13 findings as probe.md and draws zero as probe.txt, zero under a different filename, and zero at the same filename one directory down.

The preceding context answered this before you started. It pushed known-bad text through vale under this document's own path and reported whether the rules are live, so read that line rather than reasoning about it. Where it says UNSCOPED, report BLOCKED and stop. For a run where it went missing, your first lint run is what answers the question:

• The first run reports findings. The command demonstrably fires, so a later silence is real, and clearing the list gives you CLEAN.
• The first run is silent. You've learned nothing yet. Report BLOCKED and say the document may already be clean or the command may not cover this path. Never report CLEAN off a silence you haven't seen the command break.

A commit draft is the common case. The section covering one names the file at the repository root, so vale doesn't check a draft anywhere else, or one under any other name.

Figurative phrases the linter misses

The rule set names many figurative verbs and still misses the category around them. where this bites, sails through every gate, moving the goalposts, and its blast radius each passed every gate in this repository while somebody was writing the file you are reading now, and each became a rule only after a person noticed it there. Assume the phrase you are about to write sits in that same gap.

Rewording is the whole task here, which makes this run the most likely place for a phrase the gates were never going to question to enter the document.

These hold even though nothing enforces them:

• Write literally. Metaphor, idiom, and personification are all out. Rules don't fight, checks don't bite, and a document doesn't sail anywhere.
• Keep the register plain. A concrete noun and an active verb beat a vivid pair.
• Don't lengthen. A reword that doubles a sentence to avoid a rule makes the document worse in a way nothing measures.
• Don't drop precision. Swapping a specific name for a vague phrase clears a spelling rule and costs the reader the fact.
• Don't reorder or delete content for a distributional rule. Splitting a sentence is structural. Cutting a clause edits meaning.
• Don't add what the document didn't say. That covers counts, hedges, praise, and any mention of tools, sessions, or requests.

No linter checks these. An independent reviewer does, reading your before and after against each other, and its findings come back to you in also: for another pass. Getting them right the first time is what keeps that loop to one round.

Reading the output

The vale tasks print one self-contained line per finding:

12:5-19 [error] Google.Contractions match="do not" replace_with="don't" msg="Use 'don't' instead of 'do not'."

Everything you need is on that line. match gives the exact offending text. replace_with appears whenever the rule includes a replacement, and applying it verbatim beats composing your own. Read the line. Don't search for context the line already contains.

cspell prints its own shape, one line per unknown word with a location.

Findings that cost nothing

Run this first, before you read the findings at all:

mise run fix-prose-replacements <target>

It applies every finding whose rule carries its own correction, which is roughly a third of a typical run. Contractions, WordList, Semicolons, Ellipses, Ranges, and HeadingPunctuation all qualify. It refuses any finding whose span no longer holds the text the report quoted, so a stale report skips rather than corrupts the line.

What it leaves is the part that needs you. Reading a lookup so you can retype its answer is the cheapest habit to drop here.