8b679959cc
* 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>
28 lines
1.1 KiB
Markdown
28 lines
1.1 KiB
Markdown
# Product Requirements Documents
|
|
|
|
This directory contains Product Requirements Documents (PRDs) for GSD.
|
|
|
|
A PRD captures the **what** and **why** of a feature before implementation begins. ADRs (in `docs/adr/`) capture the **how** of architectural decisions. The two complement each other: a PRD makes the case for a feature and defines acceptance criteria; an ADR records the architectural mechanism chosen to deliver it.
|
|
|
|
## Naming Convention
|
|
|
|
PRDs use the same issue#-prefix slug naming as ADRs:
|
|
|
|
```text
|
|
docs/prd/<issue#>-<kebab-slug>.md
|
|
```
|
|
|
|
Example: `docs/prd/3491-bar-feature.md` for a feature tracked in issue #3491.
|
|
|
|
The GitHub-assigned issue number is the prefix. Do not compute a sequential number locally — see [CONTRIBUTING.md — "Proposing an ADR or PRD"](../../CONTRIBUTING.md#proposing-an-adr-or-prd) for the full process.
|
|
|
|
## Historical note
|
|
|
|
`docs/adr/0011-review-default-reviewers-prd.md` predates this directory and is preserved as immutable historical record. It is not a pattern to follow. New PRDs live here.
|
|
|
|
## Index
|
|
|
|
| PRD | Title | Status |
|
|
|-----|-------|--------|
|
|
| _(none yet — new PRDs use `<issue#>-<slug>.md` naming)_ | | |
|