name	docs-writing
description	Writing rules for repo prose — AGENTS.md and agents/ partials, docs/, README content, and doc comments. Load before writing or editing any of them.

Docs writing

Write every sentence as if it had always existed, for a reader who saw none of the work that produced it.

Final state only. Present tense, current behavior. No history ("previously", "now uses", "replaces"), no roadmap narrative ("will land", "phase 2 adds"), no work-in-progress state ("not wired yet"). Rationale and sequencing live in issues and PRs.
No relational framing. Never define a thing by its position among other things — "the second…", "another…", "alongside…", "unlike…", "also sanctioned". Each rule states its own scope in absolute terms and survives its neighbours being rewritten.
The deletion test. Cover the sentence; if a reader with the file open loses nothing, delete it. Restating a name, a signature, or a neighbouring sentence is a defect.
Subject, not document. Text points at the subject, never at the document or its structure ("as noted above", "this section covers", "see below") and never at the conversation or session that produced it.
Succinct means selective. Cut whole points that don't change what the reader does; write the survivors as complete sentences. Compression that costs a re-read saves nothing.

name	docs-writing
description	Writing rules for repo prose — AGENTS.md and agents/ partials, docs/, README content, and doc comments. Load before writing or editing any of them.

Write every sentence as if it had always existed, for a reader who saw none of the work that produced it.

Final state only. Present tense, current behavior. No history ("previously", "now uses", "replaces"), no roadmap narrative ("will land", "phase 2 adds"), no work-in-progress state ("not wired yet"). Rationale and sequencing live in issues and PRs.
No relational framing. Never define a thing by its position among other things — "the second…", "another…", "alongside…", "unlike…", "also sanctioned". Each rule states its own scope in absolute terms and survives its neighbours being rewritten.
The deletion test. Cover the sentence; if a reader with the file open loses nothing, delete it. Restating a name, a signature, or a neighbouring sentence is a defect.
Subject, not document. Text points at the subject, never at the document or its structure ("as noted above", "this section covers", "see below") and never at the conversation or session that produced it.
Succinct means selective. Cut whole points that don't change what the reader does; write the survivors as complete sentences. Compression that costs a re-read saves nothing.

docs-writing