Lineage-Preserving Documentation¶
Documentation artifact — instantiates Exaptive Function Redeployment
Keeps a durable, dated record of what a repurposed feature was originally built for and what it has meant, so its new use can't quietly rewrite its history.
When a feature is co-opted for a function it was never built for, the organization tends to retroactively narrate it as "we always meant it for this." Lineage-Preserving Documentation is the artifact that refuses that erasure. It records — side by side and dated — what the feature was originally built and selected for, the assumptions and meanings it carries from that origin, and the fact that a new use has been layered on top. Its defining move is that it only preserves; it makes no judgment about whether the reuse is wise and issues no decision. It is institutional memory of a lineage, kept honest precisely so the later mechanisms that do judge have a true origin story to work from rather than a flattering myth.
Example¶
An engineering team built an internal endpoint, /internal/records, in 2019 so on-call staff could inspect the database during incidents. It had no rate limiting, no authentication beyond the VPN, and a response shape that mirrored the internal table schema — all fine for a debug tool. A partner-integration team later discovered it and quietly wired it into a customer sync. Lineage-Preserving Documentation is the record that states plainly: "Built 2019 for on-call incident triage; no SLA, no public auth, response mirrors internal schema (reserved to change). Also serving Partner X's sync since ~2023." Two years on, when the schema needs refactoring, an engineer reads this record and learns the public dependency was never sanctioned — so the team plans a managed migration instead of being blindsided, and nobody can claim the endpoint "was always a public API." The record changed nothing technical; it kept the history from lying.
How it works¶
What distinguishes it from ordinary documentation is that it holds two functions at once and keeps them separate. It captures the original intent in one field and the current use in another, and never lets them merge — because the whole risk is that the new use overwrites the memory of the old. It attaches the inherited semantics (here, "schema-coupled, no SLA") as properties that were true at origin, timestamps each co-option event, and lives somewhere discoverable. It embodies Chesterton's Fence in artifact form: it records why the fence was built so that a future decision to move it can be made knowingly.[n1]
Tuning parameters¶
- Provenance depth — how far back and how detailed the origin record goes, from a one-line "built for ops" to the full original requirements. Deeper preserves more but costs upkeep and can bury the signal in detail.
- Semantic-annotation reach — how much of the inherited meaning and assumptions you capture. More surfaces future coupling risks; too much becomes speculative clutter.
- Co-location — whether the record lives next to the feature (inline, in the repo) or in a separate registry. Co-located records are seen but scattered; central ones are complete but ignored.
- Update trigger — one-time capture versus a fresh entry at each new co-option. Living records stay true but rot without an owner.
- Audience framing — written for future maintainers, auditors, or new users; this changes which parts of "the meaning" are foregrounded.
When it helps, and when it misleads¶
Its strength is that it is the cheapest insurance against history rewriting — the failure where a co-opted feature's origin is forgotten, its incidental constraints are mistaken for design guarantees, and people build load-bearing dependencies on assumptions that were never promised. It preserves the useful surprise honestly: this capacity was found, not planned.
Its failure mode is decay: a lineage record no one reads or updates is worse than none, because it wears the authority of a record while being stale. The classic misuse is running it backwards — authoring the record after the fact to make an accidental exaptation look intentional and sanctioned ("architected as a platform from day one"), which is the exact history-rewriting it exists to prevent. The discipline that guards against this is to date every entry, keep "original intent" and "current use" as distinct, append-only fields, and assign an owner who adds an entry at each new co-option — treating the record as testimony, not marketing.
How it implements the components¶
origin_function_lineage_record— its core artifact: the dated record of what the feature was originally built and selected for.historical_semantics_note— the meanings, connotations, and origin-era assumptions the feature carries (e.g. "schema-coupled, no SLA"), captured so they are not silently inherited as guarantees.
It preserves the origin but does not analyze it: the inherited_constraint_register and the flagging of which constraints will misfire are built by Origin-Context Constraint Review, and it makes no keep-or-replace ruling — that function_fork_decision_record is the Purpose-Built Replacement Gate's. Documentation only remembers; it does not judge.
Related¶
- Instantiates: Exaptive Function Redeployment — it supplies the honest origin record the rest of the redeployment machinery reasons from.
- Sibling mechanisms: Origin-Context Constraint Review · Feature Refunctioning Audit · Purpose-Built Replacement Gate · Repurposed-Feature Monitoring Dashboard · User Appropriation Review · Adaptation Delta Mapping · Legacy Feature Wrapper
Editorial Notes¶
Form Classification¶
Form family: Record, Log & Register
Rationale: Lineage-Preserving Documentation operates as a durable record, ledger, register, or trace whose value depends on preserving actual state or history because it keeps a durable, dated record of what a repurposed feature was originally built for and what it has meant, so its new use can't quietly rewrite its history.
Independent corroboration: The frozen evidence defines Lineage-Preserving Documentation as 'Keeps a durable, dated record of what a repurposed feature was originally built for and what it has meant, so its new use can't quietly rewrite its history', so its operative form is Record, Log & Register.
Review outcome: Independent reviewer agreement; high confidence.
Origin Attribution¶
Primary origin: Library & Information Science
Origin pattern: Cross-disciplinary synthesis
Present-day reach: Multi-domain
Rationale: Provenance-preserving, dated records of original purpose belong to archival and information-governance practice.
Related originating lineages:
- Computer Science & Software Engineering — Software documentation and version histories materially shape the co-located, dated record of repurposed technical features.
- Engineering & Design — Design rationale and configuration history materially shape the repurposed-feature use case.
- History & Historiography — Historical source criticism and provenance practice shape the durable separation of original intent from later reinterpretation.
- Organizational & Management Science — The mechanism primarily belongs to organizational memory and knowledge-management practice, preserving original purpose through later reuse.
Review resolution: Light authoritative research supports library_information_science as the primary provenance: Provenance-preserving, dated records of original purpose belong to archival and information-governance practice. NARA's archival guidance identifies provenance as the principle that preserves records with their origin and producing functions. The competing reviewed lineage (organizational_management) and other formative traditions remain explicit alternates rather than being erased or confused with downstream applicability. origin_mode=cross_disciplinary_synthesis records the relationship among those origin traditions, while domain_reach=multi_domain separately records how broadly the generalized mechanism can be applied.
Attribution caveat: The named artifact is an encyclopedia synthesis influenced by Chesterton's Fence and software provenance practice. The exact feature-reuse documentation pattern synthesizes archival provenance with engineering rationale capture.
Encyclopedia synthesis: The exact catalogued form synthesizes established practice rather than reproducing a single standard historical label.
Review outcome: Researched adjudication after independent review; medium confidence.
Sources consulted:
- https://www.archives.gov/research/alic/reference/archives-resources/principles-of-arrangement.html — NARA's archival guidance identifies provenance as the principle that preserves records with their origin and producing functions.
Notes¶
The record is an input, and its worth is realized only when a downstream review or gate actually consults it — which happens exactly when the exapted feature has become load-bearing enough for its history to matter. Keeping "original intent" append-only is what makes it resistant to the very rewriting it guards against: current use can be updated freely, but the origin entry should never be edited to fit the present story.
[n1] Chesterton's Fence — the principle that one should not remove or repurpose something until one understands why it was put there. A preserved lineage record is what makes that "why" recoverable years later. ↩