Pick the artifact, read that file, then write. Do not load more than one — the conventions differ and mixing them produces documents that serve nobody.
| Writing… | Read | Reader you are serving |
|---|---|---|
| A README for a public lib, CLI, or agent tool | READMES.md | someone deciding in 30 seconds whether to use this |
| A developer guide, tutorial, runbook, migration, or deprecation | GUIDES.md | someone trying to complete a task without guessing |
CLI flags, subcommands, --help, error text, output contracts |
CLI.md | someone typing at a prompt, and the script that wraps them |
| Code comments, docstrings, inline rationale | COMMENTS.md | the maintainer reading this during an outage |
AGENTS.md / CLAUDE.md operating guides |
AGENTSMD.md | an agent with no memory of your project |
| Commit messages, PR descriptions, changelog entries | PR.md | a maintainer running git log in two years |
Not this skill: blog posts and essays (use blog-review), design docs, ADRs (use grill-me), internal service wikis, or authoring a skill (use write-skill).
Workflow
- Read the implementation, schema, tests,
--help, or diff that establishes the facts. - Name the reader and the action this document must enable.
- Choose one canonical term for each repeated concept. Preserve exact API names and identifiers.
- Draft through the selected artifact lens.
- Check that every claim, command, caveat, and boundary still matches the source.
- Apply the clarity mode below, then run the checker. Treat heuristic findings as questions, not automatic edits.
Clarity modes
- Strict — procedures, safety rules, agent workflows, CLI help, and recovery instructions. Also any text whose reader cannot ask a follow-up question: tool and function descriptions, error messages, and output another agent or script parses. Put conditions before commands. Use imperative steps, one action per step, direct verbs, simple tenses, and sentences of at most 20 words.
- Natural — README narrative, explanations, comments, and PR rationale. Keep terminology and actors clear, but allow contractions, semicolons, sentence rhythm, and passive voice when the actor is unknown or irrelevant.
Apply modes by content block. A README quickstart can be strict while its motivation remains natural.
Shared rules
- Lead with the reader's goal and shortest path. Put provenance and history later or omit them.
- Be genuine. Write as a maintainer helping a reader, not as a product sheet imitating confidence.
- Use evidence instead of quality adjectives. Give the measurement, example, or boundary behind the claim.
- Use one name for one thing. Do not rotate synonyms unless they identify different concepts.
- Name the doer and the action within the first eight words of a sentence. An abstract noun as subject (
the configuration of,the handling of) hides them: make the doer the subject and the action the verb. - One idea per sentence. Open on what the reader already holds and end on the new name or value; this outranks active voice. A condition longer than ten words becomes its own step.
- Break noun stacks of four or more words: “calibration of the connection resistance,” not “connection resistance calibration procedure.”
- Say each fact once. Omit template sections that do not change the reader's next action.
- Cut words that announce or reassure:
This document describes,simply,obviously. Readers assume the opposite of an intensifier, andsimplyblames them when the step fails. - A hedge in a procedure is a missing condition: write
if X, do Y, notyou may need to do Y. In explanation, one hedge states uncertainty and two in a sentence hide it. - State unsupported cases and tradeoffs. Simpler wording must not erase precise technical meaning.
Check the draft
python3 scripts/prose_lint.py --mode strict <path>
python3 scripts/prose_lint.py --mode natural <path>
Use - for stdin and --json for structured findings. Exit 1 means strict errors; review-only findings return 0. Add <!-- prose-lint-ignore --> to ignore one line. The checker cannot detect synonym rotation without project context, so check terminology manually. This is not an STE certification or a substitute for factual review. See CLARITY-REFERENCE.md for rationale and sources.
Rewriting an existing document
- Grep tests and CI for strings pinned from the document before you restructure it. If a test pins wording, make it assert the requirement (order, a link's presence) instead of the exact text. Name the changed assertion in the PR.
- Find copies derived from it: package README, docs site, translations. Update them or state that they are out of scope.
Reviewing rather than writing
Same lens, inverted: verify the artifact against its source, then report what the target reader cannot do, cannot trust, or must read twice. Lead with the defect and its location, not with praise.