prose-standard

Prose Standard

Write enough to preserve the contract, then remove reasoning transcripts, repetition, and decoration. A contract is an obligation, invariant, precondition, postcondition, or compatibility promise that a caller, callee, implementer, producer, or consumer relies on. This skill owns editorial judgment and required prose coverage; it applies to any document or string an agent or human reads — comments, JSDoc, docs, prompts, diagnostics, and visible UI strings.

The defining constraint: a smaller word count is never the goal by itself. The goal is every factual clause preserved, nothing more. Trim or add as the proposition demands.

Preserve the complete proposition

Before editing a passage, enumerate every proposition it carries. Preserve each relevant:

• actor and action;
• condition, timing, and ordering;
• modality — must, may, never;
• negative guarantee and exception;
• ownership, side effect, failure mode, and consequence.

Remove adjectives, repetition, and narration only when every factual clause survives and the result is clearer. A smaller word count alone is not an improvement. Do not weaken a proposition to make progress.

Required coverage by location

This is not a one-way shortening pass — add prose where code and structure do not communicate a required contract.

• Public API docs: document caller-visible return distinctions, throws or rejections, side effects, ownership, timing, cancellation, and durability.
• Internal comments: orient non-local structure and obviously complicated local structure — invariants, race ordering, ownership, security boundaries, surprising failure. Delete control-flow narration and code restatement.
• Module comments: state the module's role, dependencies, responsibilities, and non-obvious architecture choices; link choices to their rationale.
• Tests: explain only non-obvious test design — why a fixture, an assertion, or an indirect observation is necessary. Delete walkthroughs.
• READMEs / package docs: include the consumer contract — configuration, semantics, failures, limitations, extension points.
• Prompts and visible strings: treat wording as behavior; inspect generated output and run behavior validation, or state why no check applies.
• Diagnostics: name the failing subject or path, the violated rule, and the correction when non-obvious. Remove internal execution narration.