# PRD writing rules These rules apply to every file in `docs/prds/`. - Search existing PRDs, issues, architecture records, and code first. Do not ask the maintainer to repeat recorded requirements. - A newer maintainer decision overrides an older design. Mark the old design as superseded instead of preserving or defending it. - Write plain English. Use a technical term only when the reader needs that exact contract or concept. - Use the shortest direct sentence. Write “When upgraded, existing instances are migrated to the database,” not a description of an importer seeding absent resources. - State each fact once. Do not repeat a heading, summarise a list before showing it, or restate a decision afterward. - Every sentence must add a decision, requirement, constraint, evidence, or verification step. Delete narration and explanations of obvious text. - Do not turn a requested outcome into extra product features. Keep inferences open until the maintainer or repository evidence settles them. - Do not create a process for a logical boundary. Add one only when it must deploy, scale, start, secure, or fail separately. - Describe working behaviour, not explanatory UI around missing behaviour. State what users can do and how success is proved. - Before approval, use independent read-only reviewers to check a cross-cutting PRD for missing behaviour and exaggerated claims. Verify and synthesise their findings; do not copy their prose. - Before requesting approval, review every sentence for complexity, repetition, and unsupported scope. - Write nothing whose truth expires. No `file.go:123` citations (cite the file and the symbol), no progress reports on the work being designed, no dated status claims, and no record of how a finding was produced. A phased plan is durable design; which phase is finished is not. Do not refer to what this document used to say: the reader cannot see it. A supersede marker is fine when it names a file, a section or a symbol they can find. `task docs:prds` enforces this. - Every PRD carries one of three statuses, and nothing else in that field. `Draft` until the maintainer explicitly approves it, `Approved` once they have and while the work is being built, `Finalised` when the work is complete. A finalised PRD does not change; supersede it with a new one instead. A revision number belongs in `**Revision:**`, a pointer to the authoritative document in `**Authority:**`, and what a past revision changed belongs in git.