Writing System
patterns ~775 tokens updated 2026-08-04
Orwell's six writing rules (1946) as an always-on prose standard for docs, PR text, commit messages, reports, and copy, plus a /rewrite command that applies them to existing text. Governs prose only, never code or technical terms.
Tags
README
writing-system
Orwell's six writing rules (1946) as an always-on prose standard, plus a /rewrite command that applies them to existing text.
What It Does
Most setups ban AI-sounding words one at a time ("no delve", "no em dashes") and still ship every README and PR description in the same AI voice. The missing piece is a writing system, not a longer blacklist. This module installs one:
rules/writing-system.mdloads in every session and governs prose: docs, READMEs, PR descriptions, commit messages, issue comments, session reports, chat responses, marketing copy. The six rules:- Never use a metaphor, simile or other figure of speech which you are used to seeing in print.
- Never use a long word where a short one will do.
- If it is possible to cut a word out, always cut it out.
- Never use the passive where you can use the active.
- Never use a foreign phrase, a scientific word or a jargon word if you can think of an everyday English equivalent.
- Break any of these rules sooner than say anything outright barbarous.
- The rule adds two workflow subsections: commit/PR prose (plain words, no achievement language, one-read test) and session reports (plain sentences, no emoji checkmarks, no "Successfully").
commands/rewrite.mdadds/rewrite [file] [mode:landing] [--apply]: lists every violation (stale phrase, long word with its short replacement, cuttable word, passive construction, jargon), then rewrites, keeping every fact, number, and name unchanged.mode:landingadds the swap test for marketing copy: if a competitor could paste the line unchanged onto their page, rewrite or delete it.
The rules never touch code, identifiers, API names, or technical terms whose plain-word swap would change the meaning.
Relationship to editorial-critique
/editorial-critique is the deep review: 8 parallel lenses over long-form writing. /rewrite is the cheap pass: one read, one violations list, one rewrite. The rule file is the standard both work from.
Manual Installation
# Global (all projects)
mkdir -p ~/.claude/rules ~/.claude/commands
cp rules/writing-system.md ~/.claude/rules/writing-system.md
cp commands/rewrite.md ~/.claude/commands/rewrite.md
Files
| File | Description |
|---|---|
rules/writing-system.md |
The six rules, scope carve-outs, commit/PR and report subsections |
commands/rewrite.md |
/rewrite: violations list, then rewrite; mode:landing for copy |
Will install
| Path | Action | Target | Type |
|---|---|---|---|
rules/writing-system.md | → | rules/writing-system.md | rule |
commands/rewrite.md | → | commands/rewrite.md | command |
Dependencies
No dependencies.
Required by
No other module depends on this one.
Included in presets
Install this module
Agent prompt
Recommended for agent users -- hands the whole install off to your assistant.
Fetch https://cd23a9be.ccgm-site.pages.dev/modules/writing-system.md and install this module into my Claude Code setup.
Native plugin marketplace
One command via the native plugin marketplace -- additive, does not merge settings.json.
claude plugin install writing-system@ccgm
The marketplace path is additive, not a replacement: it installs commands, agents, and skills as native plugin components, but it does not perform the bash installer's deep settings.json merge, and it does not write the always-loaded global CLAUDE.md context. Rules are only injected via an opt-in SessionStart hook rather than being auto-loaded. Use the bash installer when those pieces matter to you.
Files
rule (1)
rules/writing-system.md
# Writing System
**Iron Law:** PROSE FOLLOWS THE SIX RULES. FIX THE SYSTEM, NOT ONE WORD AT A TIME.
These rules govern prose: docs, READMEs, PR descriptions, commit messages, issue comments, session reports, chat responses, marketing copy. They never touch code, identifiers, API names, error strings someone will grep for, or a technical term whose plain-word swap would change the meaning ("idempotent" stays "idempotent").
## The Six Rules (Orwell, 1946)
1. Never use a metaphor, simile or other figure of speech which you are used to seeing in print.
2. Never use a long word where a short one will do.
3. If it is possible to cut a word out, always cut it out.
4. Never use the passive where you can use the active.
5. Never use a foreign phrase, a scientific word or a jargon word if you can think of an everyday English equivalent.
6. Break any of these rules sooner than say anything outright barbarous.
Check deliverable prose (a README, a PR body, a doc page, a report) against these rules before delivering it.
## What the Rules Do to a Sentence
Before: "Comprehensive error handling has been implemented across all API endpoints to ensure robust and reliable performance."
After: "We added error handling to every API endpoint."
Comprehensive, robust, reliable, and ensure are gone. Passive turned active. 16 words down to 8. Same facts.
## Commit Messages and PR Descriptions
State what changed and why in plain words. No achievement language: no "comprehensive", no "robust", no "seamless". A reviewer should know what the change does in one read. Value-first structure (what the change enables, then the evidence) comes from the git-workflow rules and the `pr-description` skill; these rules govern the words inside that structure.
## Session Reports and Summaries
Report progress in plain sentences: what changed, what failed, what comes next. No emoji checkmarks, no "Successfully", no "Perfect", no wall of bullets. Start with three lines; add detail only when it changes the reader's next action.
This governs free-form summaries. When a command or skill mandates an exact output format (a JSON envelope, `/sds`'s final report, a statusline, a structured findings artifact), that format wins.
## Why There Is No Word Blacklist
Banning words one at a time ("no delve", "no em dashes") treats symptoms. The six rules are the system; a banned-word list is what you fall back on without one. For a deep, line-by-line review of long-form writing, run `/editorial-critique`; its detectors (AI-tell vocabulary, filler phrases) apply these rules at review time. For a quick single pass over existing text, run `/rewrite`.
## Red Flags
Stop and rewrite if you catch yourself:
- Writing "comprehensive", "robust", "seamless", or "cutting-edge" in prose
- Opening a report with an emoji checkmark or the word "Successfully"
- Writing a sentence whose subject performs no action ("error handling has been implemented")
- Padding a summary with bullets that restate the diff
- Swapping a precise technical term for a folksy one and losing the meaning; rule 6 exists for this
command (1)
commands/rewrite.md
---
description: Rewrite prose under the six writing rules - list every violation first, then rewrite, keeping every fact, number, and name unchanged
allowed-tools: Read, Edit, Glob, Grep, AskUserQuestion
argument-hint: "[file-path or pasted text] [mode:landing] [--apply]"
---
# /rewrite - Apply the Six Writing Rules
Single-pass rewrite of existing prose under the six writing rules in `~/.claude/rules/writing-system.md`. Violations first, then the rewrite. Facts, numbers, and names survive untouched.
For a deep multi-lens review (argument, structure, data, impact), use `/editorial-critique` instead. This command is the cheap pass: one read, one list, one rewrite.
## Step 1: Resolve the Target
- If `$ARGUMENTS` contains a file path, Read it. Critique the prose only: skip frontmatter, fenced code blocks, inline code, and command output.
- If `$ARGUMENTS` contains pasted text, use it directly.
- If neither, ask what to rewrite.
Parse flags from `$ARGUMENTS` before treating the rest as the target: `mode:landing` and `--apply`.
## Step 2: List Every Violation
Go through the text and list each violation, grouped by rule, quoting the exact original text:
1. **Stale figures of speech** (rule 1): each print-worn metaphor or simile, with a fresh or literal replacement.
2. **Long words** (rule 2): each long word with its short replacement ("utilize" -> "use", "approximately" -> "about").
3. **Cuttable words** (rule 3): each word or phrase that can go without losing meaning ("in order to" -> "to", "it's worth noting that" -> cut).
4. **Passive constructions** (rule 4): each passive with its active rewrite, where the actor is known.
5. **Jargon** (rule 5): each jargon or foreign phrase with an everyday equivalent, only where precision survives the swap. A technical term with no accurate plain substitute stays.
If a category has no violations, skip it. Do not pad the list.
## Step 3: Rewrite
Produce the full rewrite applying every fix from Step 2.
Hard constraints:
- Keep every fact, number, and name unchanged.
- Keep code blocks, identifiers, commands, links, and frontmatter byte-for-byte.
- Keep the document's structure (headings, lists, tables) unless a violation lives in the structure itself.
- Rule 6 wins conflicts: if a fix makes the sentence worse, leave the original and say so.
Output the rewrite in a fenced code block so it pastes clean (see `copy-paste-output.md`).
## Step 4: mode:landing
For marketing or landing-page copy, add two checks on top of Steps 2-3:
- **One concrete claim per line.** Flag any line that makes two claims or none.
- **The swap test.** For every line, ask: could a competitor paste this unchanged onto their page? If yes, the line says nothing about this product. Rewrite it around a concrete, specific claim, or delete it.
List swap-test failures in Step 2's output as their own group.
## Step 5: Apply
- If the target was a file and `--apply` was passed, apply the rewrite with Edit.
- If the target was a file without `--apply`, show the violations and rewrite, then ask whether to apply.
- If the target was pasted text, the fenced rewrite is the deliverable; there is nothing to apply.