Git Remembers What Changed. It Rarely Remembers Why.

Ask an experienced engineer why a strange piece of production logic exists, and they will often start with Git. `git blame`—who last touched this line. `git log`—the sequence of commits that got here. Or they ask the veteran who was there.

The linked ticket. The pull request discussion.

Sometimes an architecture decision record. Those tools are good. They are also incomplete in a way that matters more every year.

Git remembers what changed. It often remembers who changed it and when.

It sometimes remembers a ticket title. It rarely remembers why the change was believed to be safe—and under what conditions that belief should be challenged. That gap is not a documentation nit. It is an organizational memory problem dressed up as engineering hygiene.

What Git actually preserves

Version control is one of the best memory systems most companies already run. It preserves the current answer in code, a chronological sequence of diffs, authorship and timestamps, branches and merges, often a ticket or incident link, and sometimes review comments that capture part of the debate. That is real institutional value. If the question is, “What does the code do today, and how did the bytes get here?”, Git is usually the right place to start. If the question is, “Should we change this, and what would make the old decision wrong?”, Git is usually not enough.

The senior engineer who lived through the incident remembers more than the diff: the assumption that failed, the cleaner alternative that made production worse, the expected outcome that never quite arrived, and why the ugly “temporary” fix lasted five years. Those are not metadata fields Git enforces. They are experience.

The familiar reconstruction ritual

Picture—illustratively, not as a measured field study—a service that retries a payment callback with a strangely specific backoff. A new engineer—or an AI coding assistant—can read the function. Git can show the commit that introduced it. The ticket might say: “Reduce duplicate charges during provider timeouts.”

A test asserts that a particular sequence must not double-post. All of that is useful. None of it fully answers what would make the next change safe: what the provider was believed to guarantee then; which alternatives were rejected and why; what latency, error rate, or customer impact was expected to improve; what evidence would make the backoff the wrong control now; which downstream contract would have to change before deleting it would be responsible. Without those answers, people do what organizations always do. They reconstruct a story from whatever artifacts remain.

Sometimes the story is accurate. Often it is merely plausible. Plausible history is how accidental dogma gets written into code comments and PR templates.

The same gap shows up outside the repository. A runbook, SOP, or case note that records the fix—but not the assumption behind it or when to reconsider it—leaves the next person reconstructing why. Captured lessons should still be challengeable by practitioners who were there.

Tickets and ADRs are not automatically memory

The usual engineering response is reasonable: Write better commit messages. Require ticket links.

Adopt ADRs. Improve PR templates.

I am not against any of that. A clear commit message is better than `fix stuff`. An ADR that records context, decision, and consequences is better than folklore alone. Sometimes an excellent ADR does preserve assumptions, rejected alternatives, expected outcomes, and reconsideration conditions.

That helps—and does not falsify the thesis. It shows the selective-memory bar, and how rarely ambient hygiene reaches it without intent. But most of those artifacts still preserve the answer. They say what we chose. They less often preserve:

• the assumptions that had to be true;
• the rejected alternatives and the reasons they lost;
• the expected outcome against which the decision could later be judged;
• the reconsideration conditions that would make the old lesson questionable.

An ADR that omits those is still documentation of a conclusion. It is not yet organizational experience. This is the same distinction as documentation versus memory—only now the museum is your repository. Classical knowledge management already says searchable artifacts are not tacit judgment.

What changes now is speed and fluency: when AI retrieves incomplete Git history and invents a polished why at coding speed, reconstruction stops being a quiet onboarding tax and becomes an operating risk. Better search over commits—or a larger context window over the same incomplete history—does not create the missing continuity.

“Just write better commit messages” is not the fix

There is a tempting moral lecture here. If engineers were more disciplined, the why would already be in Git. That lecture fails in practice for the same reasons universal documentation mandates fail everywhere else.

People skip them under deadline pressure. They fill them with ceremony. They write what reviewers expect to see, not the hard parts they are unsure about.

They document the chosen design and quietly omit the failed experiments that actually taught the team something. And even when someone does write an excellent commit message, the organization rarely treats it as a living record with ownership, evidence, and a retirement condition. It becomes another artifact to retrieve. Retrieval is not the same as retained experience.

So yes—improve commit quality where it helps. Use ADRs for consequential decisions. Link incidents when they matter. Just do not confuse a hygiene campaign with a memory system.

If the strategy is “make every change carry full causal context,” the strategy will fail. Selective capture—focused on high-consequence decisions—is more honest. It is also still difficult. In principle form, not product form: a named owner for the lesson, a link to the evidence that justified it, and an explicit retirement or reconsideration trigger.

Without those three, selective capture is still folklore with better filing—and someone still has to decide what is worth preserving and what stays out of scope.

AI coding makes the why-gap sharper

AI-assisted coding did not invent this problem. It made the cost of ignoring it more visible. Coding assistants are increasingly good at retrieving related commits, summarizing pull requests, and proposing explanations for why code looks the way it does.

That can be helpful. It can also be dangerous—as a working hypothesis about the failure mode, not a measured prevalence claim. If the organization preserved the diff but not the assumption, the ticket but not the rejected alternative, or today’s workaround but not the reconsideration condition, the model can retrieve what was stored—and generate a fluent narrative that sounds like institutional knowledge.

A fluent narrative is not historical truth. In a human team, a wrong reconstruction is often challenged by someone who was there. In an AI-assisted workflow, the reconstruction can arrive with the confidence of autocomplete and the polish of a senior engineer’s prose. The reviewer may not notice that the “why” was invented.

The next commit may encode the invented why as if it were settled fact. That is how incomplete memory becomes accelerated folklore—when the mechanism fires. The failure mode is not “AI wrote code.” The failure mode is treating commit retrieval as if it recovered organizational experience the organization never stored.

Questions that expose the why-gap

For a high-consequence change, these are diagnostic probes—not a schema for a new memory product, and not a shopping list that replaces ADRs, tickets, or PR templates you already have. If nobody can answer them—whether in an ADR, an incident write-up, or a short note beside the ticket—the organization preserved the patch, not the experience. What was happening? Incident, customer failure, regulatory constraint, scale cliff, dependency breakage—what triggered the work?

What did we believe then? Not what we know after three more outages. What evidence was actually available at decision time?

What assumptions did the change depend on? Provider behavior, consistency guarantees, traffic shape, data quality, team capacity, adjacent system ownership.

What alternatives were rejected? And why—performance, risk, time, irreversibility, incomplete evidence? What did we expect to happen? A decision without an expected outcome is hard to evaluate later.

What actually happened? Did reality support the reasoning, partially support it, or contradict it? When should we reconsider it? What change in dependency behavior, workload, product requirements, risk tolerance, or evidence would make the old lesson the wrong guide?

Those probes point toward memory: causal continuity, not only state. They also make old lessons easier to challenge intelligently. “We tried that before” is dogma. “We tried that before under assumption X; reconsider if X is no longer true” is experience.

Engineering cultures already respect the second form when it lives in a trusted person’s head. The open question is how much of it can belong to the organization without freezing past choices into permanent policy—or inventing a parallel bureaucracy beside tools teams already use.

Git is not the villain

None of this is an argument against version control. Git is extraordinary at what it was designed to do: preserve the evolution of a textual artifact with integrity and collaboration primitives. Tickets are useful.

PR review is useful. ADRs are useful. The mistake is asking those systems to be a complete substitute for organizational experience.

They remember change. They do not automatically remember judgment. As more of the coding loop is assisted by systems that retrieve and summarize repository history, that distinction stops being philosophical.

It becomes an operating risk. A new engineer can inherit the current tree. A new model can inherit whatever fits in context.

Neither inherits tenure unless the organization preserved the conditions, failures, and reconsideration criteria that tenure usually carries. The hard question is not whether your commit messages could be clearer—most could. It is whether, the next time someone changes the strange payment backoff, they inherit enough of the why—selectively kept for high-consequence decisions, with evidence and a named owner who can retire the lesson—to avoid inventing a plausible story.

Git will still remember what changed. Whether the organization remembers why remains an open operating question.