Files
archie/docs/prds/RULES.md
T

43 lines
2.5 KiB
Markdown

# 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.