43 lines
2.5 KiB
Markdown
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.
|