Writing System

Rule text

# Writing System

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.

## STE-lite Limits

The measurable half of ASD-STE100. `ccgm-prose-lint` checks the sentence and paragraph limits (noun clusters and unnamed references are judged by reading): before delivering a document, run `test -x "$HOME/.claude/bin/ccgm-prose-lint"` as its own command; if it exits non-zero, note that the linter is not installed and go on; otherwise run `"$HOME/.claude/bin/ccgm-prose-lint" --strict FILE` as its own command.

- Instruction sentences: 20 words or fewer. Descriptive sentences: 25 or fewer.
- Paragraphs: 6 sentences or fewer, one topic, topic sentence first. Each list item counts as its own paragraph.
- Noun clusters: 3 words or fewer. Break longer ones with a preposition.
- Steps: imperative, one action per sentence, condition before the action.
- One term per concept within a document.
- Name a reference the first time it appears in text for the operator: "PR #1138 (autoheal signature quality)", not "#1138".
- Same scope as the six rules: prose only. Code, identifiers, error strings, and technical terms are exempt.

## 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

View raw (4138 bytes)