Reconciliation Report¶
Document — instantiates Mapping Reconciliation
Documents decisions, unresolved conflicts, exceptions, tests, adoption guidance, and change impacts for a reconciled mapping.
Reconciliation Report is the human-readable narrative that a reconciliation leaves behind — the document that tells a reader who was not in the room what was decided, why, what remains unresolved, and what adopting the reconciled mapping will change for them. Its defining feature is that it is explanatory prose for an audience, not an operational table: where a conflict matrix stores decisions in cells and a validation run produces pass/fail evidence, the report narrates those outputs into rationale, adoption guidance, and change-impact analysis a downstream team can act on. It ties each material decision to its reasoning, packages the reconciled mapping for a specific released version, and — importantly — states plainly what the reconciliation did not resolve, so residual ambiguity is disclosed rather than buried. It is the deliverable that makes a reconciliation trustworthy to people who must live with it: auditable, adoptable, and honest about its limits.
Example¶
A national statistics agency updates its occupation classification, remapping an old census occupation coding scheme to a revised one, and analysts across government depend on the time series staying comparable. A Reconciliation Report accompanies the release. It narrates the material decisions: the old catch-all Computer specialists code was split into four new codes, and the report explains the rule used and why one legacy category was mapped to a broader new one to preserve historical comparability. It states the change impact bluntly — "trend analyses spanning the boundary year must apply the provided bridge coefficients; naïve joins will show a spurious jump in software roles" — and gives adoption guidance for re-basing existing dashboards. It carries a residual section listing the handful of occupations whose old-to-new mapping remains genuinely ambiguous and should be treated as uncertain. And it is stamped to a specific classification release, so a reader knows exactly which version of the mapping the narrative describes. The report does not choose the mappings or run the tests; it explains and packages what was chosen and tested, for the people who will use it.
How it works¶
- Narrate decisions into rationale. Each material choice is written up with the reasoning behind it, so a reader can reconstruct why, not merely what — the audit trail as prose.
- State change impact and adoption guidance. The report spells out what adopting the reconciled mapping will break, shift, or require, and how to migrate — turning a raw mapping into something a downstream team can safely take up.
- Disclose the residue. Unresolved and intentionally context-dependent cases get their own visible section, so the report never lets a clean summary imply a completeness the reconciliation didn't achieve.
- Bind to a release. The narrative is pinned to a specific published version of the mapping, so the explanation and the artifact it explains cannot drift apart.
Tuning parameters¶
- Audience register — technical implementers versus executives or the public. The register sets depth and vocabulary; a report pitched at the wrong audience is either unreadable or useless.
- Rationale coverage — every decision documented versus only the material or contested ones. Full coverage is thorough but bloated; selective coverage is readable but risks omitting a choice someone later questions.
- Impact-analysis depth — a summary of changes versus a full downstream-effect and migration analysis. Deeper analysis serves adopters better but takes real effort and dependency knowledge.
- Residual prominence — how visibly unresolved cases are surfaced (buried appendix vs. headline section). Prominent residuals build trust; buried ones invite the reader to assume false completeness.
When it helps, and when it misleads¶
Its strength is that it makes a reconciliation usable and auditable by outsiders — the people who must adopt the mapping, migrate their systems, or later audit the decisions, none of whom were present when the choices were made. A good report is what lets a reconciliation survive its authors' departure. It is also the natural place to disclose residual ambiguity honestly, in prose that a table cannot carry.
Its failure mode is post-hoc rationalization[n1]: a report written to justify a mapping after the fact rather than to document how it was actually derived, smoothing over the messy or contested choices to present a cleaner story than the reconciliation earned. A classic misuse is a report that omits the residual section and the change-impact warnings, leaving adopters to discover the breakage themselves. The guarding discipline is to write the report from the decision trail and the validation evidence rather than around them, and to treat the residual and change-impact sections as mandatory, not optional — so the document records the reconciliation faithfully instead of flattering it.
How it implements the components¶
Reconciliation Report realizes the documentation-and-disclosure face of the archetype:
traceability_record— the report narrates each material decision to its rationale and evidence, giving the reconciliation an auditable, human-readable trail.versioned_mapping_release— it packages the reconciled mapping for a specific published version, with adoption guidance and change-impact analysis for that release.residual_ambiguity_log— unresolved and context-dependent cases get an explicit, visible section rather than being smoothed away.
It does NOT implement reconciliation_rule — choosing how conflicts resolve is Crosswalk Reconciliation Workshop — nor validation_test, running the tests it reports on, which is Code Crosswalk Validation. The report documents decisions and results; it neither makes nor tests them.
Related¶
- Instantiates: Mapping Reconciliation — the narrative document that makes a reconciliation adoptable and auditable.
- Consumes: Code Crosswalk Validation — the report writes up the decisions and the validation evidence a reconciliation produced.
- Sibling mechanisms: Crosswalk Reconciliation Workshop · Schema Mapping Review · Ontology Alignment Session · Mapping Conflict Matrix · Translation Memory Review · Standard-Setting Process
Editorial Notes¶
Form Classification¶
Form family: Representation, Specification & Plan
Rationale: Reconciliation Report operates by externalizes reconciled decisions, rationale, change impacts, and migration guidance in a report. That concrete deployed or enacted form is Representation, Specification & Plan under the frozen taxonomy.
Nearest alternative: Record, Log & Register — Although Record, Log & Register can support this mechanism, the frozen evidence makes its operative form the act that externalizes reconciled decisions, rationale, change impacts, and migration guidance in a report; the alternative is therefore secondary rather than defining.
Review outcome: Adjudicated after independent review; medium confidence.
Origin Attribution¶
Primary origin: Computer Science & Software Engineering
Origin pattern: Cross-disciplinary synthesis
Present-day reach: Multi-domain
Rationale: Because the object is a reconciled mapping with tests, exceptions, adoption guidance, and change impacts, the complete artifact is systems-integration practice; audit reconciliation supplies the accuracy-control lineage.
Related originating lineages:
- Accounting & Auditing — Reconciliation practice contributes the explicit disposition of every discrepancy.
- Organizational & Management Science — Change-management practice materially adds adoption guidance, impacts, and unresolved decision ownership.
Review resolution: The blind reviewers disagreed on primary lineage. Light authoritative research resolves the defining form in favor of computer_science: Because the object is a reconciled mapping with tests, exceptions, adoption guidance, and change impacts, the complete artifact is systems-integration practice; audit reconciliation supplies the accuracy-control lineage. The rejected primary is retained only when it materially shaped the mechanism, and present-day breadth is recorded separately as domain_reach=multi_domain.
Review outcome: Researched adjudication after independent review; high confidence.
Sources consulted:
Notes¶
[n1] Post-hoc rationalization — constructing a tidy justifying account of a decision after it was made, rather than recording the reasoning that actually drove it. A reconciliation report is exposed to it because a document written to sell a mapping reads much like one written to record it — which is why sourcing the report from the decision trail and validation evidence is the discipline that keeps it honest. ↩