* docs: adopt issue#-prefix naming for ADRs/PRDs (#3485)
The repo's sequential ADR/PRD numbering convention has produced
recurring collisions when developers compute "next number" locally
and ship in parallel — currently visible on disk as duplicate
docs/adr/0010-*.md and triplicate docs/adr/0011-*.md, plus a stack
of "resolve ADR conflict" commits in git history.
Replace the local-compute convention with issue#-prefix slug naming:
docs/adr/<issue#>-<slug>.md (new ADRs)
docs/prd/<issue#>-<slug>.md (new PRDs — directory introduced)
GitHub issue numbers are server-assigned and atomic, so the
reservation step the CONTRIBUTING.md issue-first rule already enforces
also produces the artifact ID. One issue = one ADR-or-PRD = one PR.
Same shape as the existing changeset random-name pattern (#2975) for
CHANGELOG.md fragments, applied to a different artifact class.
Migration policy: legacy ADRs 0001-* through 0011-* are preserved
as immutable historical record. The new convention applies only to
ADRs/PRDs created on or after this merge.
Files updated:
- docs/adr/README.md — naming convention + legacy note + link
- docs/prd/README.md (new) — seeds the new directory + same convention
- CONTRIBUTING.md — new "Proposing an ADR or PRD" section
- docs/contributor-standards.md — formalize as contributor requirement
No code surface — docs-only.
Closes#3485
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs(changeset): add Changed fragment for ADR/PRD naming convention (#3487)
Per CONTRIBUTING.md "When unsure whether a change is user-facing, add
the fragment" — the contributor process IS user-facing for the
contributor user class. Drop the no-changelog opt-out, surface the
naming-convention change in the next CHANGELOG so contributors see
it before they hit it as a PR rejection.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: address CodeRabbit findings on #3487
- CONTRIBUTING.md: rename heading to "Proposing an ADR or PRD" so its
GitHub-anchor slug matches the #proposing-an-adr-or-prd link target
used from docs/adr/README.md, docs/prd/README.md, and
docs/contributor-standards.md (broken anchors)
- docs/adr/README.md, docs/prd/README.md, docs/contributor-standards.md:
add `text` language tag to the new naming-convention fenced blocks
to satisfy markdownlint MD040
Pre-existing untyped fences elsewhere in the touched files are left
alone per CONTRIBUTING.md "no drive-by formatting".
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
