Simplify Prose

Simplify Prose

Rewrite prose that already exists so a reader gets the point on the first pass. writing style governs prose being written for the first time. This skill is the pass for everything written before that standard applied, or written under time pressure, or inherited from someone else.

The rewrite is proposed before it is applied. An in-place edit of someone's document is not reversible by reading the response, so the human sees the exact changes and approves them first.

Quick start

1. Read the target. Measure it against the countable targets below.
2. Identify every rewrite, and every span the preservation rules put off limits.
3. Present the proposal: each change as line → before → after, plus what stays and why.
4. Stop. Nothing is edited before the human answers.
5. On approval, apply the edits and report the new measurements.

The standard

Plain language as defined by plainlanguage.gov and ISO 24495-1. Seven rules carry almost all of it:

• One idea per sentence. A sentence carrying two ideas becomes two sentences.
• Active voice with a named actor. The parser reads the CSV, not the CSV is read. Passive is correct only in the three cases in REFERENCE.md.
• The common word wherever the technical one adds no precision. use not utilize, start not initiate, about not with respect to, enough not sufficient. A real term of art stays; see the substitution table's keep column.
• Unwind nominalizations. we decided not a decision was made. A -tion, -ment, or -ance noun usually has a verb trapped inside it.
• Define an unavoidable term on first use, once, in a clause. The dispatcher binds a lease — the exclusive write claim a writer holds on a path — before...
• Lead each paragraph with its point. The reader who stops after the first sentence should still get the claim.
• Address the reader as you where the document tells them to do something.

Countable targets

Measure these before and after. Report both numbers in the proposal.

These are proxies and nothing more. A document can hit every number and still be unreadable, and a good document occasionally misses one on purpose. They exist so the proposal shows the human something concrete instead of asserting improvement. Never report a target as a grade, a score, or a passing result.

Length is a ceiling, not a target

writing style requires varied sentence and paragraph length, and calls uniform three-clause rhythm the clearest sign nobody chose the shape of the text. A short-sentence rule applied naively produces exactly that rhythm.

So the 35-word cap is a ceiling. Under it, vary length deliberately: a four-word sentence after a twenty-eight-word one is the point, not a defect. Chopping every sentence to a uniform fifteen words satisfies the arithmetic and fails the standard. The two rules are not in conflict, and a future reader should not "resolve" them by deleting one.

Preservation rules

Rewrite prose. Nothing else. Never modify:

• fenced code blocks, inline code spans, command transcripts, argv, or diffs;
• YAML frontmatter keys, JSON and schema keys, or field names;
• required headings — their text, order, count, and casing. The seven ## sections in write-design are the case to watch: that skill freezes their names and order to match an upstream template;
• numbers, units, metric names, file paths, identifiers, or option flags;
• link targets. Link text may be rewritten; the URL never changes.

This is the contract rule from writing style applied to editing rather than authoring. Structure wins over style. Where a contract dictates wording, keep the contract wording, report the conflict, and rewrite the prose around it.

Approval gate

Present the complete proposal, then stop and wait. State:

• the measurements before, and what they become after;
• every proposed change as line → before → after, grouped by which rule drives it;
• every span deliberately left alone, and which preservation rule protects it;
• any place where the standard and a contract conflict, and which one you kept.

Present the proposal as a concise numbered batch in ordinary prose and wait for a reply. Where the real decision is a choice among competing rewrites of the same passage, number the alternatives so the human can answer by number.

Do not invoke runtime plan-mode transitions, and never treat an internal plan state as approval. This repository reserves plan mode for approving saved artifacts, and an in-place edit is not an artifact write. The same reasoning governs commit.

Approving a rewrite approves that rewrite. If the file changes on disk after the proposal, measure again and present a fresh proposal rather than applying a stale one.

Input modes

A file path is the primary mode. It ends in an in-place edit of that file, after approval.

Pasted text has no file behind it. Return the rewrite and the change list in the response and write nothing. Do not create a file to hold the result, and do not search for a file the text might have come from.

If the user names a file that does not exist, say so and stop. Do not create it.

When a rewrite would break a contract

Leave the span alone. Report it as a conflict, naming the rule that wanted the change and the contract that blocks it, and rewrite the rest of the document.

Never silently skip a conflicted span, and never narrow the job to the easy parts without saying so. A conflict is a finding the human may want to act on elsewhere.

Out of scope

• Code. Readability of code belongs to simplify; this skill treats code as a preserved span even when the code is unclear.
• Authoring new prose. A new HLD is write-design; a new handoff is write-agent-handoff.
• Facts. The rewrite preserves meaning. If a sentence appears wrong, report it as a question; do not correct it under cover of a style pass.
• Structure. Adding, removing, reordering, or renaming sections is a rewrite of the document, not a simplification of its prose. Propose it separately.

Routing

• Unclear code → the built-in simplify.
• A new design document → write-design.
• A commit subject → commit, whose subject-format rules win over this standard on any conflict.
• Prose inside a template-bound artifact → rewrite the prose here, and leave the template structure to the skill that owns it.

Additional resources

• REFERENCE.md — the substitution table, passive-voice and nominalization detection, the measurement procedure, document-type adjustments, and the pre-edit self-check.
• EXAMPLES.md — worked runs covering an in-place edit, a contract conflict, and pasted text.
• writing style — the authoring standard this skill extends to existing documents, and the contract rule it inherits.