Design Rationale Changelog¶
Rationale record — instantiates Legacy-Form Refashioning
A dated, running record of every preserve / translate / fade / discard decision and its reasoning, so future maintainers can tell an invariant from a temporary bridge.
A Design Rationale Changelog is a chronological decision record: for each legacy form, an entry stating what was decided — preserve, translate, fade, or discard — why, when, and on what evidence. Its defining property is that it captures reasoning over time, not structure: it is a narrative history of how a transition was steered, so a maintainer arriving years later can tell which forms are load-bearing invariants and which are temporary scaffolding due to be shed. It exists to defeat institutional amnesia — the state in which a team treats either the old medium or the new one as inevitable because no one recorded that a choice was ever made.
Example¶
A transit agency spends three years refashioning its network map and rider app, and keeps a running changelog of every form-level decision. One entry, dated early: kept the colour-coded line convention (bridge cue) — rider recognition depends on it; revisit once app wayfinding is primary. A later one: faded geographic accuracy toward a Beck-style schematic — decision: legibility invariant outweighs geographic fidelity; dissent from the GIS team logged. A later one still: discarded the printed-timetable grid in the app — replaced by live arrivals; shedding gate passed when the great majority of trips were being checked in real time. Each entry is dated, attributed to an owner, and linked to the evidence behind it. When a new designer joins two years on and proposes "restoring" geographic accuracy, the log tells her in minutes that the choice was deliberate, why, and who objected — so the debate resumes from the record instead of from scratch.
How it works¶
- One entry per decision. Each record names the form, the verb applied (preserve, translate, fade, or discard), the reasoning, the date, the owner, and the evidence — the full provenance of a single choice.
- Log the bridge cues and their reasons. Record why each borrowed cue was adopted and the fade condition intended for it, so a temporary cue stays recognisable as temporary in the record itself.
- Log the gates that fired. Note when each shedding gate was passed and on what evidence, preserving the audit trail of every fade.
- Keep it append-only and linked. The history is immutable and cross-referenced to the artifacts it describes, so the reasoning cannot be quietly rewritten after the fact.
Tuning parameters¶
- Granularity — every micro-decision versus major transitions only. Fine granularity yields a complete audit trail but a log no one reads; coarse granularity stays readable but loses the small choices that later surprise people.
- Attribution depth — decision-plus-dissent versus outcome only. Recording dissent preserves the real debate and protects minority objections; recording only the outcome is lighter but flattens the reasoning.
- Linkage — how tightly entries reference the evidence and the artifacts they describe. Tight linkage makes the log auditable; loose linkage is faster to keep but degrades into anecdote.
- Audience — an internal maintainers' log versus a public transparency record. Public logs build external trust but constrain candour; internal ones are franker but invisible to the people the transition affects.
When it helps, and when it misleads¶
Its strength is that it keeps a transition legible to its own future: no team is condemned to treat the old or the new medium as inevitable, and an auditor can confirm that a critical obligation actually survived the crossing rather than assuming it did.
Its failure mode is a changelog that records what changed but not why — a list of edits with no reasoning is un-auditable, and a log so exhaustive that no one reads it is scarcely better. The classic misuse is post-hoc rationalisation: entries written after the fact to justify a decision already made, so the record documents a story rather than a choice.[n1] The guarding discipline is to capture the reasoning and evidence at decision time, before the outcome is known — a rationale is only trustworthy if it could have argued the other way.
How it implements the components¶
lineage_and_rationale_record— it is the record: the dated, attributed reasoning behind every preserved, translated, faded, or discarded form.legitimacy_bridge_cue— it logs why each bridge cue was borrowed and the fade condition intended for it, keeping temporary cues legible as temporary in the history.phased_shedding_gate— it records when each shedding gate was passed and on what evidence, preserving the audit trail of every fade.
It does not build the static field-by-field map of old elements to new structures (transfer_invariant_set, inherited_constraint_filter) — that is Format Crosswalk and Migration Guide; the crosswalk is the map, the changelog is the dated history of how the map changed. Nor does it measure per-cohort readiness (audience_readiness_segmentation); that is User Readiness Signal Panel.
Related¶
- Instantiates: Legacy-Form Refashioning — supplies the standing lineage record that keeps a transition's reasoning available to its future maintainers.
- Consumes: Format Crosswalk and Migration Guide — references the crosswalk's mappings as the artifacts whose changes it dates and justifies.
- Sibling mechanisms: Skeuomorphic Onboarding Interface · Side-by-Side Legacy / Native Mode · Affordance Discovery Prototype · Legacy Pattern Deprecation Schedule · Format Crosswalk and Migration Guide · Substrate-Native Showcase Release · User Readiness Signal Panel
Editorial Notes¶
Form Classification¶
Form family: Record, Log & Register
Rationale: Design Rationale Changelog operates as a durable record, ledger, register, or trace whose value depends on preserving actual state or history because it a dated, running record of every preserve / translate / fade / discard decision and its reasoning, so future maintainers can tell an invariant from a temporary bridge.
Independent corroboration: The frozen evidence defines Design Rationale Changelog as 'A dated, running record of every preserve / translate / fade / discard decision and its reasoning, so future maintainers can tell an invariant from a temporary bridge', so its operative form is Record, Log & Register.
Review outcome: Independent reviewer agreement; high confidence.
Origin Attribution¶
Primary origin: Computer Science & Software Engineering
Origin pattern: Cross-disciplinary synthesis
Present-day reach: Multi-domain
Rationale: Software architecture cohered chronological decision records that preserve context, choice, rationale, and consequences as designs evolve.
Related originating lineages:
- History & Historiography — Historical method supplied diachronic reconstruction and distinction between enduring invariants and temporary bridges.
Review resolution: Software architecture cohered chronological decision records that preserve context, choice, rationale, and consequences as designs evolve. The retained alternate lineages materially shaped the mechanism's form.
Attribution caveat: The changelog extends Architectural Decision Records to explicit preserve/translate/fade/discard histories.
Encyclopedia synthesis: The exact catalogued form synthesizes established practice rather than reproducing a single standard historical label.
Review outcome: Reconciled after independent review; high confidence.
Notes¶
[n1] Architectural Decision Record (ADR) — the software-engineering practice (popularised by Michael Nygard) of logging each significant design decision with its context, the choice made, and its consequences, at the time it is made. A design rationale changelog applies the same discipline to a medium transition; the ADR tradition is also where the warning against writing records as after-the-fact justification is sharpest. ↩