Craft
Changing a PRD Mid-Sprint: Amend It the Same Day
Mid-sprint spec changes are normal; where they get written down is the problem. How to land an amendment in the PRD the same day, in a change block people see.
Specs change mid-sprint. An engineer finds a case nobody named, a customer call reframes a limit, a dependency slips. None of that is a process failure. It is what building something produces.
The failure is where the change gets recorded. It is decided in a thread or a call, implemented in code, and never written back into the spec. By the end of the sprint the PRD describes a feature nobody is building, and the only accurate record is spread across four people's memory and a chat search.
That is the third of the six ways specs fail: the decision that left no trace. The fix is two habits. The amendment lands in the document the same day it is decided, and it lands visibly, in a change block at the top, so the person who read the spec on Monday finds out what moved without re-reading all of it.
Three kinds of change
Not every change needs the same people. Sorting them first stops a small clarification turning into a meeting, and stops a re-scope slipping through as a clarification.
| Kind | What it is | Example | Who agrees |
|---|---|---|---|
| Clarification | Fills a gap the spec left open | What the empty state says | Owner confirms |
| Amendment | Changes something the spec decided | A limit, a rule, a state's behaviour | Owner, plus whoever signed that section |
| Re-scope | Changes what is in, what is out, or the metric | Dropping a flow, adding a segment | Owner and the accountable approver |
The line between the last two is the sprint goal. If the change puts the sprint goal out of reach, it is a re-scope however small the edit looks, and the approver needs to hear about it today rather than at the demo. For amendments, the people who signed for that section re-sign it and nobody else does.
Clarifications still go in the document. They are the cheapest kind and the most often skipped, because they do not feel like decisions. They are, and the next person to hit the same gap will answer it differently.
The change block
It sits at the top of the spec, under the status line, newest first. An illustration of one entry:
CHANGES SINCE APPROVAL (v3, 9 Oct)
16 Oct · Amendment · §4, R4.3
Was: shared filters return the same results for every member.
Now: results exclude rows the viewer cannot access; a notice shows
how many were hidden.
Why: filters could expose restricted rows to members without access.
Agreed: product owner, engineering lead.
Affects: FLT-21 (in progress), FLT-18 (done, needs rework),
test cases TC-40 to TC-44.
Was and now. The delta, readable without opening the section.
Why. One line. This is the part that stops the change being reversed next month by someone who assumes it was an accident.
Agreed. Names, not "the team". If the owner made the call alone, say so.
Affects. The tickets and test cases that encoded the old behaviour. This is the line that turns a spec change into a sprint action. Done work that needs rework is the most expensive thing a mid-sprint change produces, and the thing most likely to be discovered at the demo.
Then edit the section itself. The body always says what is true now; the block says what moved. Both, every time:
- Body edited, no block: the change is silent. Anyone who read the spec before today is building the old version and has no reason to look again.
- Block written, body unchanged: the spec becomes an errata list. Section 4 still says the old thing, and every reader has to reconcile the two in their head.
A short marker at the edited line, (changed 16 Oct, see changes), connects the two for someone who lands on the section directly.
Why the same day
Because the reasoning decays faster than the decision. By tomorrow the call is a memory of a call, the thread has scrolled, and whoever writes it up is reconstructing rather than recording. A change written down a week later is a justification.
And because the build does not wait. Every hour between the decision and the write-up is an hour in which someone builds or tests against the old text.
The practical rule is the one from handoff: if it was decided in a conversation, it goes into the document before the conversation ends, while the people who decided it are still there to check the wording. If it cannot be written down yet, it was not decided yet. It is an open question, and it goes in the spec as one.
The change nobody announced
The most common mid-sprint change is not discussed at all. An engineer hits a case the spec does not cover and picks an answer, because the sprint is moving and the answer seemed obvious. Usually it is a reasonable answer. It is still a product decision, made without review and recorded only in the code.
Punishing that does not work; it teaches people to stop asking and guess quietly. Make the cheap route easier instead: a comment on the spec at the relevant line, "Decided at implementation: X. Confirm?", which the owner turns into a clarification entry the same day. Thirty seconds for the engineer, a minute for the owner, and the decision exists somewhere other than a diff.
Telling the team
Post a link to the change-block entry in the team channel, and on each ticket in the Affects line. Do not restate the change in the message.
Restating feels helpful and creates a second copy. Next week someone searches the channel, finds the message, and builds from it, after the change has been amended again. A link always points at the current text.
What goes in the decision log instead
The change block records how this spec moved. The decision log records decisions that will outlive it, with what was rejected and what would change the call.
Most amendments only need the block. The ones that also need a log entry are the ones someone will want to reopen: an alternative that will look attractive again, a constraint that might lift. In the shared-filters illustration, "we considered showing restricted rows as redacted, and rejected it because the row count alone leaks information" is a log entry. The block says what changed. The log says why the obvious alternative is not the answer.
When the changes pile up
A few amendments in a sprint is normal. If the change block is longer than the section it changes, the spec was approved before it was decided, and the honest move is to say so. Send it back to review with a line explaining why, so that its status tells readers what they are holding. That is a reset, and it is cheaper than a sprint of amendments to a premise that no longer holds.
At the end of the build, the block stays. It is the record of what the build taught you, and it is what the next person reads when they ask why the feature does not match the original pitch.
FAQ
Can you change a PRD during a sprint? Yes. Write it into the spec the same day, with what changed, why and who agreed.
Who needs to agree to a mid-sprint spec change? The owner for a clarification, plus the section's signers for an amendment, plus the approver for a re-scope.
What is a change block in a PRD? A dated list at the top of the spec: was, now, why, who agreed, and what it affects.
Does a mid-sprint change go in the decision log or the spec? The spec always; the log too when the change rejected an alternative someone will propose again.