PRD Versioning
How to handle PRD changes after build starts without silently mutating the spec.
Why
Once engineering starts building from a PRD, any change to the spec is a change to the contract. Silently editing the PRD mid-sprint means the engineer is building against a spec that no longer matches what was agreed, and the acceptance criteria drift without anyone noticing. Versioning — bumping the PRD version and recording what changed and why — keeps the audit trail intact. When the feature ships and someone asks 'why did we build X instead of Y?', the version history answers it instead of a Slack archaeology dig.
When
Any time the PRD changes after stakeholder sign-off. Takes 5 min per change. Never skip — unversioned changes are the root of 'that's not what I asked for'.
How
1. Keep PRDs in git (docs/prd/NNNN-title.md) so changes are tracked 2. On any post-sign-off change: a. Bump the version header (v1 → v2) with the date b. Add a "## Changes" section: what changed, why, who approved c. Notify all sign-off stakeholders of the change 3. If the change alters acceptance criteria, re-run the PRD review checklist 4. If the change is > 20% of scope, treat as a new PRD and re-plan the sprint 5. Never delete old versions — git history is the audit trail
Example
# PRD-003: release-notes-generator (v2, 2026-03-22) ## Changes from v1 - Added requirement: auto-detect security commits (requested by Security team) - Why: 30% of releases omit security fixes in notes - Approved by: Alice (eng), Dan (legal) — 03-22 - Removed from scope: gitlab support (moved to v2 of the product) - Why: de-scoped to hit launch date; gitlab is 5% of users - Approved by: Carla (sales) — 03-22 Stakeholders notified in #prd channel 03-22.
Common Problems
- ⚠Burying changes in edit history without a summary — engineers don't read git diffs of PRDs; surface changes in a dated Changes section.
Best Practices
- ✓Pin the PRD version in the sprint ticket so it's clear which spec version the build targets.
- ✓When a change is de-scoped, record who agreed to the de-scope — 'we ran out of time' is not an approval.