Prose Review

Prose review

Review prose written to be read by someone else for language that doesn't belong in text its intended reader will encounter, and for missing grounding that a cold reader would need. Fix problems directly.

The main in-scope forms are:

• User-facing documentation: READMEs, guides, reference docs, help text

• Prompts for other LLMs: skills, system prompts, agent instructions, handoffs, task briefs

• Inline comments: the // and # prose a maintainer reads next to the code

• Docstrings: function, class, and module documentation, including generated API docs

• Other-facing messages: issue or PR comments, status notes, release notes, messages, emails, and similar prose when the operator names them

The same failure modes run through all of them.

First: name the reader

Before reviewing each file or standalone artifact, state in one line who reads it, what they are trying to do, what they can and cannot see, and what genre it is (user README, contributor or architecture doc, operator runbook, agent prompt, handoff, task brief, inline comment, docstring, message, email, issue comment). Every judgment below is relative to that reader and purpose, not to a generic "new reader." Implementation detail is correct in a contributor-facing architecture doc or an inline comment and wrong in a user README; "what changed" is correct in a changelog and wrong in reference docs. Do not strip detail that this file's actual reader needs.

The intended reader must be able to use each artifact correctly with only its text and explicitly named, reachable dependencies, without access to the session, private plans, or other local material that informed the recent edits.

For prompts, handoffs, and task briefs: could a cold-start agent act correctly from this text and any explicitly named, reachable files, without access to the context window you currently have and without having to guess? For comments and docstrings: could a maintainer who can read the surrounding code, but who wasn't present when it was written, understand what this text is telling them?

Call this operational closure: every dependency needed to understand or act is either contained in the artifact or identified through a path or access method the recipient can actually use.

Then ask the second question, which decoding alone never answers: is this language situationally appropriate for that reader, with the right register, level of detail, and content for this point in the document? A sentence can be fully comprehensible to a README-reading human and still be badly designed for them.

What to catch

Leakage: wrong content is present

• Implementation-plan language: internal field names, spec edge-case notes, architecture references, phrases like "reserve the timestamp column" or "compact display buckets" that reflect how something was built rather than what a user or other agent sees

• Changelog/diff language: "does not change X", "deliberately preserves Y", "without affecting Z", "is intentionally out of scope." These compare against a prior version the reader has no baseline for. In comments and docstrings this shows up as narrating the edit ("now also handles X", "moved from Y", "renamed for clarity") instead of describing the code as it currently stands. Genre exception: when the file under review is a changelog, release note, migration guide, task retrospective, planning doc, PR description, or a handoff or task brief whose purpose is to transmit current state and remaining work, this language may be the point of the document. Preserve necessary temporal deltas, and don't "fix" them into timeless prose. The test is never whether the text refers to a prior state; it is whether this reader opened this file expecting it to

• Internal jargon: type names, config key internals, data-flow descriptions that only matter to contributors

• Agent/session artifacts: review constraints, schema-version strategy, compatibility decisions leaked from planning conversations

• Orphaned deixis: "this", "that", "the above", "as discussed", "the same approach", "the earlier plan", "continue from here." These references depend on a referent in the authoring session or a private plan rather than the document; restate the referent or delete the reference. In comments this also covers pointers the reader cannot open: ticket numbers, plan filenames, review threads, "per the discussion"

Omission: needed content is absent

• Terms used as if defined: project-specific terms, acronyms, and metric names that the reader needs but that are defined nowhere they can see; the fix is a local definition or glossary entry, not deletion

• Unreachable dependencies: instructions that require files, systems, credentials, or steps the reader has no path to discover or perform from where they stand

• Under-grounded prompts, handoffs, and task briefs: missing task goal, inputs or paths, definitions, decision-relevant constraints or rationale, expected output, success criteria, or stop conditions; required dependencies that are neither included nor named in a reachable way. Anything that forces a cold-start recipient to guess or confabulate

• Under-grounded comments and docstrings: a comment that restates what the code plainly does while omitting the non-obvious constraint, invariant, or reason the code is shaped that way; a docstring that assumes caller context the caller cannot see (units, ownership, error behavior, what the caller must guarantee)

Omission failures are as common as leakage and harder to see, because the text reads fine to anyone who already has the context. Hunt for them by simulating the named reader, not by scanning for bad phrases. The appropriate fix for omission is often addition rather than removal.

Misfit: content is present and comprehensible, but wrong for this reader here

• Register mismatch: engineering-internal voice in text a non-engineer reads; clipped note-taking style where a user needs a sentence; ceremony and hedging where a maintainer wants one line

• Granularity mismatch: exhaustive precision where the reader needs the shape of the thing, or a vague gesture where they need the exact flag, path, or value

• Relevance mismatch: accurate, defined, and decodable, but not what this reader needs at this point: rationale nobody asked for, caveats that matter to three people, edge cases placed ahead of the common path

• Order mismatch: material arranged in the author's discovery order rather than the reader's need or dependency order, so the reader must carry unexplained terms until they pay off later

• Answer-display mismatch: text demonstrates that the author possesses all the relevant concepts but does not construct a usable path from the recipient's starting point. The expected terms are present, but hierarchy, prerequisites, emphasis, or a clear through-line are missing

Misfit is the failure mode that survives a careful leakage-and-omission pass, because every individual sentence is true, defined, and readable. Catch it by asking what the reader came to this file to do, and whether this paragraph helps them do it right now.

Also catch any other pragmatic perspective-taking error that produces poor recipient design. One common pattern resembles the "curse of knowledge" described by Colin Camerer, George Loewenstein, and Martin Weber: language models behave as though human or AI recipients share the current context window or ephemeral planning artifacts, then leak local jargon or omit grounding. Treat this as a serious recurring failure across user-facing and agent-facing prose.

Curse of knowledge is one lens within the broader job. Recipient design (Sacks, Schegloff, and Jefferson; closely related to Bell's "audience design") covers the whole task of shaping an utterance for its actual recipient: what they know, what they came for, how much detail serves them, what register fits the situation, what they need first, and what they must be able to do afterward. Text can pass every shared-knowledge check and still answer a question the reader never asked, in a voice written for somebody else. Hold both lenses at once: "can this reader decode this?" and "is this the right thing to say to this reader, here?"