AddThisFeature

Record Merge

Combine two duplicate records into one without losing anything attached.

involved Data & Content

What it adds

A merge flow that picks a surviving value per field, reparents all related data, redirects old references, and can be audited afterwards.

What your agent is told to do

5
  1. 1

    Show the two records side by side, field by field, and require an explicit survivor for every field where they differ. Do not default to 'newest wins' silently; the user is merging because they know which one is right.

  2. 2

    Reparent every related object — children, comments, attachments, activity, links, memberships — onto the survivor in a single transaction. A half-finished merge is worse than two duplicates.

  3. 3

    Detect relationships that would become duplicates after reparenting (the same person as a member of both records, the same tag applied twice) and collapse them rather than violating a uniqueness constraint mid-merge.

  4. 4

    Redirect old references: keep the losing record's ID resolvable and point it at the survivor, so bookmarks, external links, and API consumers do not break.

  5. 5

    Lock both records for the duration of the merge and write an audit entry recording who merged what, which values survived, and when. Do not build identity or account merging here — that is owned by Account Merge — and do not add pre-create duplicate warnings, which are owned by Duplicate Detection on Create.

Edge cases it handles

6
  • Concurrent edits to either record during the merge must be rejected or forced to re-read, not silently discarded.
  • Merging a record into itself, or merging records the actor can only partially see, must be refused up front.
  • Records in different workspaces, tenants, or permission scopes must not be mergeable without an explicit rule for which scope survives.
  • Timestamps need a decision: created_at should usually take the earlier of the two, not the survivor's.
  • Merges are effectively irreversible once children move. Either implement an undo window or say plainly in the confirmation that it cannot be undone.
  • Very large merges — thousands of children — must run in the background with progress, not block a request until it times out.

Definition of done

8
  • Every conflicting field requires an explicit survivor choice before the merge can run.
  • All related records move to the survivor within one transaction, with no orphans left behind.
  • Relationships that would duplicate after reparenting are collapsed instead of erroring.
  • The losing record's ID still resolves and redirects to the survivor.
  • Both records are locked during the merge and concurrent edits are rejected.
  • An audit entry records the actor, both records, and the surviving values.
  • The feature matches the existing design system.
  • No existing functionality is broken.

Related features

How it works

  1. 1

    Copy the link

    Grab the Markdown instruction URL for this feature.

  2. 2

    Give it to your AI

    Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.

  3. 3

    It inspects, then implements

    Your agent reads your existing app first, then adds the feature to fit it.

Works with your stack

These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.

Need it tighter than that? Customize the feature and tell it exactly what you're running.