Decision Lifecycle Map

Kata: Map the lifecycle of a superseded decision. Pick a decision in your team's history that was made, lived for some time, and was then replaced. Produce the artifacts and the timeline so a reader can follow the full arc.

Retrieval Prompts

1. State the ADR status lifecycle from memory: Proposed, Accepted, Rejected, Deprecated, Superseded.
2. When is in-place amendment valid, and when must you supersede?
3. What is the difference between Deprecated and Superseded?
4. Why is deleting an outdated ADR a governance mistake?
5. What is the difference between context drift and implementation drift?

Compare and Distinguish

• Amending vs superseding. What triggers each?
• Context drift vs implementation drift. What response does each call for?
• Deprecated (no replacement) vs Superseded by ADR-X. How do you decide which fits?
• Supersede vs "silently edit." What does the second cost you?

Common Mistake Check

Identify the failure mode in each:

1. An Accepted ADR is edited in place to reflect a new database choice; no superseding ADR exists. (destroys reasoning trail)
2. An obsolete ADR is deleted from the repo. (removes evidence)
3. An ADR is marked Deprecated with no replacement planned for 18 months. (deprecation without a path - becomes a zombie)
4. Two ADRs contradict each other; neither references the other. (orphaned conflict)
5. A superseding ADR does not link back to the ADR it supersedes. (future readers lose the trail)

Mini Application

Construct a complete lifecycle map for one decision.

Step 1: Pick the decision. Something your team (or a public project) decided and later replaced. Examples: message broker choice, deployment platform, state management library, auth provider.

Step 2: Locate the original ADR. If none exists, write a retrospective one in Nygard template dated at the original decision time. Status: Superseded.

Step 3: Locate the triggering event. What changed between the original decision and the new one? Was it context drift (world changed) or implementation drift (code diverged)?

Step 4: Write the superseding ADR. In its Context section, link back to the original and state specifically what changed.

Step 5: Update the original ADR status. Write: Superseded by ADR-NNN (YYYY-MM-DD). See ADR-NNN for the current decision.

Step 6: Build the timeline. A simple table:

Date	Event	ADR
YYYY-MM-DD	Original decision accepted	ADR-XXX
YYYY-MM-DD	Trigger observed (incident, migration, deprecation notice, etc.)	-
YYYY-MM-DD	Draft superseding ADR opened for review	ADR-NNN (Proposed)
YYYY-MM-DD	Superseding ADR accepted	ADR-NNN (Accepted)
YYYY-MM-DD	Original status flipped to Superseded	ADR-XXX
YYYY-MM-DD	Remediation complete (migration done, rule enforced, etc.)	-

Step 7: Reflect. In 2-3 paragraphs, answer:

• Could the original ADR have been written in a way that made the replacement easier?
• What signal would have surfaced the need to supersede earlier?
• Is there a fitness function or drift audit that would have caught this?

Critique and Rewrite

Pick a superseded ADR in a public repo (or synthesize one if none available). Rewrite both the original and the superseding ADR so that:

• the original, if read alone, directs the reader forward
• the superseding ADR, if read alone, gives a reader the historical context without needing to read the original
• the trigger for replacement is named explicitly
• at least one consequence of the replacement itself (migration cost, compatibility hazards) is captured

Evidence Check

This page is complete only when you can:

• produce a superseded + superseding pair with correct cross-links
• distinguish context drift from implementation drift for a real decision
• name the trigger event that justifies supersession
• write a timeline that a new team member could follow
• propose one fitness function or audit practice that would have shortened the time-to-supersede