The documents you get, not just the software.

Two systems hold records that are meant to agree. They are compared by hand, on a cadence that depends on somebody remembering, and a disagreement is usually noticed by the person it inconveniences rather than by the process that produced it. The work replaces that with a service that compares both sides on a fixed schedule, closes the differences it has a rule for, and reports the ones it does not.

This section is written back to the buyer in their own words, and the scope is not agreed until they recognise their problem in it. A scope built on a problem statement the client would have phrased differently is already wrong, and most of the disagreements that surface later trace back to this paragraph.

• Reconciliation run: A scheduled comparison of both records, producing a set that matches, a set of differences a rule can close, and a set that needs a person.
• Resolution rules: The rules that close a difference without a person, written down and versioned with the service rather than living only in the code that applies them.
• Exception queue: Where a difference that no rule closes goes to be looked at, with both source records attached so that it can be acted on without a second investigation.
• Operational surface: What the operators need in order to run, pause and inspect a reconciliation without asking an engineer.
• Handover: The runbook, the access handback, and a working session with the people who will operate the service afterwards.

• Changing either system of record. Both are read as they are, and the service holds no opinion about which one is right beyond the rules agreed here.
• Automatic correction of a difference that no rule covers. The service reports it. A person decides.
• Historical backfill beyond the window named in the assumptions below.
• Anything found after this document is agreed, unless it arrives through the change path at the end of it.

The out-of-scope list is the half of a scope document that does the work. What is in scope is the part both parties already agree on. What is out of it is the part they each assumed differently and have not noticed yet.

• Stage one, read both sides: Accepted when a run reads both records end to end from a cold start and produces a difference set that is reproducible: the same inputs give the same output, and the run can be repeated without side effects.
• Stage two, close what has a rule: Accepted when every rule in the agreed set is exercised by a test that names the case it covers, and when changing a rule is a reviewed change to the rule set rather than a change to the service.
• Stage three, hand the rest to a person: Accepted when a difference with no matching rule reaches the exception queue with both source records attached, and clearing it is possible by somebody who was not on the build.
• Stage four, operate it: Accepted when the operators run a full cycle themselves, from the runbook, with the build side watching rather than driving.

An acceptance criterion is a sentence somebody can be held to. If a line here cannot be checked by a person who was not on the build, it is a hope rather than a criterion, and it does not belong in this section.

Each line below is taken as true in order to sequence and price the work. If one turns out to be false the scope changes, and the change is visible rather than absorbed.

• Both records are readable without a change to the systems that own them, and read access can be granted for the length of the engagement.
• The rules that close a difference can be written down. Where a rule turns out to be a judgement somebody makes case by case, it stays a judgement and the difference goes to the queue.
• One person on the client side can decide what counts as a match. Reconciliation work stalls faster on an unanswered definition than on an unwritten line of code.
• Volumes and timing stay inside the range recorded at kickoff, which is the one place in this document a figure appears.

• A false assumption: The assumption it contradicts is named, and the change is priced against the difference rather than reopening the whole document.
• A new requirement: It arrives as an amendment with its own stage and its own acceptance criterion, or it waits.
• A stage that fails acceptance twice: The second failure says something about the criterion and not only about the work, so both are looked at before the third attempt.
• Nothing else: A scope that drifts without a written amendment is not a scope, and by the end nobody can say what was agreed.

The scope is agreed by both sides in writing, and the version agreed is the version the engagement is held to.

Each run appends its differences to a ledger rather than updating a table of currently open mismatches. A difference is a row with a first-seen marker, a last-seen marker and a resolution, and it is never edited in place: closing it appends a resolution, and seeing it again appends an observation.

Current state, which is what an operator actually looks at, is derived from the ledger rather than stored beside it.

• A mutable table of open differences: The obvious shape and the cheapest to write. Not taken, because it answers only what disagrees right now. The question this service exists to answer is when the two sides started to disagree and what closed it, and a table overwritten on every run cannot answer that at all.
• A log with no derived view: Keeps the whole history and costs almost nothing to write, but pushes the reconstruction onto every reader, including the operator clearing an exception at speed. Not taken, because the operational surface is a deliverable here rather than a side effect.
• Reconciliation inside one of the two systems: Removes a moving part and an integration. Not taken, because it makes one system the arbiter of a disagreement it is a party to, and because the scope rules out changing either one.

The rejected alternatives are the part of an architecture memo that is usually lost, and the part that is most expensive to reconstruct later. A memo that records only the decision leaves the next engineer to rediscover the three shapes that do not work.

• The ledger grows without bound until a retention rule is agreed, and that rule is an open question below rather than a decision taken here.
• Every read of current state costs a derivation. The derived view is a cache, and a cache is a second thing that can be wrong.
• Correcting a mistake means appending a correction, which is slower to write and harder to explain to somebody expecting a row they can edit. The runbook carries that explanation for exactly this reason.

• A retention rule that discards history faster than the ledger earns its keep. If a closed difference may be forgotten after a short window, the mutable table becomes the honest choice.
• A requirement to edit a resolution rather than append a correction, arriving from an auditor rather than from convenience.
• Derivation cost that stops fitting inside the run cadence the scope agreed. That is a measurement, and it belongs in this section only once somebody has taken it.

• Retention: How long a closed difference is worth keeping is undecided, and it is a business question rather than an engineering one.
• Rebuild or maintain: Whether the derived view is rebuilt on every run or maintained incrementally. Both are viable, and the choice depends on the volumes in the scope document, which a specimen does not fill in.
• Who owns a rule change: Rules are versioned with the service, which makes changing one an engineering event unless somebody on the client side is given the authority to change it without one.

An open question stays in the memo, with a name against it, until it is answered. Deleting it because it is uncomfortable is how a system acquires a decision nobody remembers taking.

An architecture memo is amended, never rewritten. A superseded decision keeps its section and gains a note saying what replaced it and why, because the reasoning that turned out to be wrong is often the most useful thing in the file.

• Start a run: Runs are scheduled, and starting one by hand is a supported action. It is safe to repeat: a run is idempotent by design, so a second run over the same window produces the same difference set.
• Pause the schedule: Pausing stops new runs and lets an in-flight one finish. It is the correct first move whenever either source system is being maintained.
• Clear an exception: Open it, read both source records attached to it, then either apply an existing rule or record the resolution as a one-off with a reason. A one-off that recurs is a missing rule, and gets raised as one.
• Add a resolution rule: Rules are versioned with the service, and adding one is a reviewed change. The review exists because a wrong rule closes differences silently, which is worse than not closing them.

• A source system is unreachable: The run fails whole rather than partially, nothing is written, and the schedule keeps trying. No action is needed unless the outage outlasts the acceptable lag recorded below. Do not force a partial run: a difference set built from one side is not a difference set.
• A run finishes with an implausible number of differences: Assume a source changed shape before assuming the two sides diverged. Pause the schedule first, because a run against a misread source fills the exception queue with noise that then has to be cleared by hand.
• The derived view disagrees with the ledger: The ledger is authoritative. Rebuild the view from it. The rebuild is safe at any time and does not need the schedule paused.
• An exception nobody available can resolve: Leave it open. An unresolved difference is a known unknown, and holding those is what this service is for. A guessed resolution is a wrong record that then looks correct forever.

A runbook that says to check the logs has not been written yet. The addresses below belong in the live document, filled in at handover and kept current as they move.

Some things are not automated on purpose. A runbook that does not say which ones leaves the next engineer to automate them and find out why afterwards.

• Closing a difference no rule covers. A person decides, because the alternative is a service that invents agreement.
• Adding a rule. Reviewed rather than self-service, for the reason given under routine operations.
• Restoring from a backup. Rehearsed and documented, but started by a person, because an automatic restore triggered by a false alarm is its own incident.

• The service reports disagreement. It does not decide which side is right, except where a rule says so.
• History grows until a retention rule is agreed. The architecture memo carries this as an open question, and it is repeated here because the operator is the one who notices it first.
• A rule change applies to runs after it and not to differences already closed. Reopening a closed difference is a deliberate action with its own procedure, never a side effect of editing a rule.

A limitation section that is empty means it was not written. Every system has behaviour somebody will be surprised by, and naming it here is cheaper than having it discovered during an incident.

Handover is not complete while the build side can still reach the system. Every credential issued during the engagement is revoked or rotated, and the handback is recorded against the access checklist that issued it.