Writing for humans

The reader is an engineer looking for a specific fact under time pressure. They are not reading for comprehension of a narrative; they are scanning for the parameter, the constraint, or the step, and every sentence that does not carry one is a sentence they had to reject before reaching the one that did.

--mode write drafts; --mode audit applies the same rules to prose already on the page. Absent, infer from the target: an empty or missing file is write, an existing one with content is audit.

House convention outranks the wording and formatting rules here — a project style guide, an existing docs set with a settled voice, a vendor template. It does not override the source contract or the verification scan.

Source contract

Work from source material the user supplies: a specification, a codebase, an existing document, a transcript. Where the source is missing, incomplete, or self-contradictory, name the gap and stop short of it. Do not fill it from general knowledge of how such systems usually work — a plausible invention is indistinguishable from a verified fact once it is on the page, and the reader has no way to tell which they are acting on.

A contradiction between two parts of the source is reported, not silently resolved. Say which parts disagree and what each claims.

Literal

State what something is, what it does, or how to do it. Never state what it is like.