me-cedric Spec drift triage
A specification moved after the tickets were created. Answer three questions for each affected ticket: what changed, what to do, and is this a change request.
Its twin is spec-to-tickets, which writes the
first version of the text.
Where the facts are
docs/delivery/tickets.json— the registry. Each entry carries a state and a fingerprint per field.docs/delivery/tickets.plan.json— the operations the sync tool proposes now.- The specification, under
specs/. - The patch:
git diff <base>...HEAD -- specs.
The sync tool computes the drift. It fingerprints the projection that would be sent to the tracker, field by field, and compares it with the fingerprint it recorded. You read that result. Never recompute it by eye.
The four states
| State | Meaning | Default action |
|---|---|---|
synced |
the projection matches the recorded fingerprint | nothing |
drifted |
the specification moved, the ticket did not | update the ticket |
conflicted |
both the specification and the ticket moved | comment only |
orphaned |
the specification section is gone | comment only |
conflicted never becomes an update. A human edited that ticket after the tool
wrote it, and an update would delete their work without a review.
orphaned never becomes a deletion. Work that lost its specification may still
be in progress, or already done. The entry stays in the registry forever.
Summarise the delta in the vocabulary of the ticket
Write what a person who reads only the ticket needs. Name the field that moved, then the consequence.
| Instead of | Write |
|---|---|
| a diff hunk | the acceptance criterion that changed |
| a file path | the requirement, by its title |
| "the spec changed" | "the currency check now also rejects an unknown code" |
| a list of every field | only the fields whose fingerprint moved |
Say what did not move. "The acceptance criteria changed; the estimate did not" is the sentence that stops a needless re-estimation.
Keep the summary to five lines. A longer note is a sign that the delta is a new requirement, not a correction.
Say what to do
One line per ticket, in this shape:
<TICKET-KEY> · <state> · <what moved> → <action>
The action is one of: update the description, comment only, re-estimate,
split into a new ticket, or no action.
Choose no action when the edit is a typo, a heading, or a reformatting. A
fingerprint that did not move is proof, and a typo that moves no fingerprint
touches no ticket.
Choose split into a new ticket when the specification gained a requirement
rather than correcting one. Growing an existing ticket hides the growth.
Is it a change request
Flag a delta as a change request candidate when any of these is true:
- The specification gained a requirement or a scenario that was not there.
- The estimate of the linked costing task has to grow.
- A ticket already in progress or done needs work again.
- The delta moves a date, a scope boundary, or a deliverable.
A wording correction, a clarification of an existing rule, and a typo are not change requests. Say so plainly, so nobody bills a typo.
Write the flag, never the decision. The commercial answer belongs to the person who owns the contract.
Output
Write the triage to docs/delivery/drift/<YYYY-MM-DD>-<kebab-slug>.md.
---
title: <one line>
date: <YYYY-MM-DD>
base: <the base reference>
---
# <title>
**In one sentence:** …
## Tickets to act on
| Ticket | State | What moved | Action | Change request |
| --- | --- | --- | --- | --- |
## Change request candidates
One paragraph for each. What the client asked for before, what the specification
says now, and which tickets carry the extra work.
## No action
Tickets whose fingerprint did not move, with the reason in three words.
Do not do these
- Do not edit
tickets.json. The sync tool owns the registry. - Do not propose a status transition or a deletion.
- Do not overwrite a ticket a human edited. Comment instead.
- Do not claim a drift you did not read in the registry.