Evidence Before You Reconcile

When two versions of a system have drifted far apart, the request usually arrives as one line: "reconcile these two branches." It sounds like a merge. It almost never is. The real first question is not how do we combine these? but do we yet know enough to combine them safely? Most of the time, the honest answer is no — and the most valuable work you can do is to establish enough external truth to make that call deliberately.

The problem

A long-lived divergence is tempting to treat as a large but ordinary merge. You map the conflicts, you start resolving them, you push. The trouble is that the conflict count is the most visible part of the problem and often the least dangerous. The dangerous parts are the ones that don't show up in a diff: where the system is actually deployed from, what the production database history really looks like, and whether the files in the repository still describe reality.

A merge tool can only reason about the text in front of it. It cannot tell you that one branch is the live production source, or that a set of database migration files has been rewritten in place since they were applied. So the first failure mode isn't a bad merge — it's starting the merge at all, before anyone has confirmed what is true outside the repository.

What actually happened

A reconciliation effort was deliberately scoped to do no reconciling. Its only job was to gather evidence and produce a staged plan: classify the divergence, find out what was deployed where, and decide which work was safe to attempt and which was not.

That framing changed everything. The branch divergence turned out to be stable and well understood — a known baseline, a known conflict footprint. The genuinely hidden complexity was elsewhere. The deployment mapping had to be confirmed rather than assumed: once it was established that production deployed directly from the main line, overwriting or resetting that line became a production-impacting act, not a housekeeping one.

The database was the sharpest finding. A set of historical migration files had been edited in place on one branch. The migrations were recorded as already applied in production by version — but whether their current contents still matched what had actually run could not be confirmed from the available tooling. "Applied" is a statement about version identifiers. It is not a statement about content. That gap quietly blocked any work that depended on those migrations, even though nothing in the code conflicts hinted at it.

So the work stopped exactly where it should: a clear map instead of a finished merge. Some narrow, genuinely independent changes could proceed. Anything touching migrations or production state was marked blocked. A few questions — which branch was the authoritative source, whether the rewritten migrations matched production — were left explicitly for a human to confirm, not guessed.

The lesson

Reconciling diverged systems is not a version-control problem. It is a version-control and deployment and database-history problem, and the last two are usually invisible in the place you're looking. Three ideas carried the work:

Treat external state as a first-class deliverable. Where the system deploys from, and what the production database actually contains, are not background context to be assumed. They are evidence to be gathered and written down, with the same weight as the code itself.

"Applied" is not "matches." A migration recorded as applied tells you a version ran. It does not tell you that the file now sitting in your repository is what ran. When historical migrations have been edited after the fact, you cannot treat the repository as the source of truth for production — you have to verify content parity before anything depends on it.

Keep your vocabularies separate. A branch named "main" is not the same thing as a database environment named "production." Conflating the two — letting branch names stand in for deployment or data reality — is how a safe-looking merge quietly becomes a production incident.

The broader principle

Evidence has states, and naming them is what makes a plan trustworthy. A piece of evidence can be sufficient (we know this and can act on it), unknown (we haven't established it yet, so we must not assume it), or blocking (we know enough to know we must not proceed here). A fourth state matters more than it looks: superseded. Early in any investigation you record things as unknown; later findings replace them. If you don't mark the supersession explicitly, a reader six weeks later mistakes a stale "unknown" for current truth — or worse, treats a since-cleared risk as still live.

This is why evidence-gated planning is its own phase, distinct from execution. The point of the gate is not bureaucracy; it is to stop "we have mapped the problem" from being misread as "we are cleared to fix it." Mapping ninety conflicts is not permission to start resolving them. The gate is what keeps a hard-to-reverse, outward-facing change from being driven by the most visible evidence instead of the most important.

How to apply it

Before you reconcile two diverged systems, build an explicit evidence matrix and fill it in before touching anything:

• Version-control state — the baseline, the merge base, and the real conflict footprint.
• Deployment mapping — what is actually deployed, and from where. Confirm this before discussing any strategy that rewrites a shared line.
• Data and migration state — which environment maps to which, what migrations are recorded as applied, and — critically — whether edited historical migrations still match what ran in production.
• Source authority — which side is authoritative where, recorded as a human decision rather than an assumption.

Then stage the work by risk, and do not collapse the stages into one:

1. Evidence — gather and classify external truth; resolve nothing.
2. Safe-first batches — only changes genuinely independent of migration and production state.
3. High-risk batches — migration- and authority-dependent work, gated on the verifications and human decisions the evidence phase surfaced.

Mark every piece of evidence with its state, and when later findings change the picture, record the supersession in plain sight. The deliverable of this work is not "ready to merge." It is a clear account of what is safe, what is blocked, and why — which is exactly what lets the merge, when it finally happens, be boring.