Review

What a match will not decide is kept as a review item for a person or an agent, and a match can leave its whole changeset as a draft to approve.

A match decides the cases its rules settle and leaves the rest. What it leaves is recorded, so the question outlives the run and someone can answer it later. There are two things to review: review items, which are questions about records, and drafts, which are changesets a run was told not to commit.

This page raises one review item of each kind, answers each, and approves a draft.

Before you start

The examples use the sample project with both of its files of rows loaded and matched, which is where Getting started ends. If you have that project and its server is running, use it. If not, this makes it:

spool init companies
cd companies
spool dev

Leave that running. In a second terminal, in the companies directory:

spool load samples/crm-1.csv
spool match
spool load samples/crm-2.csv
spool match

The three kinds of item

KindThe questionRaised when
possible_mergeWhich identity does this record belong to?A new record matches members of two or more identities.
conflictDoes this record belong here or not?A new record matches one member of an identity and a no_match rule holds against another.
possible_splitAre these records still one thing?A row is taken back, and nothing is left that joins the identity's other records.

A record in an open possible_merge or conflict has no identity. An identity in an open possible_split stays as it is. Nothing is merged or split without someone deciding.

A record that fits two identities

The sample has a Halden Group in GB and one in the US, kept apart by the country rule. Load a Halden Group with no country:

halden.csv
id,name
c-13,Halden Group
spool load halden.csv --source crm
spool match
Output
loaded  1 row into source `crm`, type `company`: 1 new
next    `spool match` places it in an identity
run         8, type `company`
examined    1 record, 2 candidate pairs
judgements  2 match, 0 no_match
placed      0 records, 0 identities created
left out    1 record in 1 review item: `spool show review` says why
spool show review
Output
item  kind            status  type     raised by  about
1     possible_merge  open    company  run 9      1 record without an identity, which matched 2 identities
ITEM=$(spool show review --status open | awk 'NR==2 {print $1}')
spool show review $ITEM
Output
review item  1
kind         possible_merge
status       open
type         company
raised by    reconcile run 9

record                                source and key  now
621ab95e-5f9e-6b91-e660-455831fe854a  crm:c-13        waits for an identity

identities they matched
  01a1efc6-41cd-775d-8758-e731c61371cb
  01a1efc6-41cd-775d-8758-e7329447fd9a

The record matched both Halden Groups by name, and with no country the rule that keeps them apart had nothing to compare. Joining either would be a guess, and joining both would merge two identities, which a match never does. So the record has no identity, and a possible_merge item says why.

The studio, at http://127.0.0.1:7765/, shows the same item on its Review screen, with the record beside each identity it matched and a button to assign it to each:

The studio's Review screen with one open item: the record crm:c-13, Halden Group, beside the two identities it matched, each with a button to assign the record to it

Decide it

A reviewer who knows that c-13 is the British company places it there with a changeset of one assign:

RECORD=$(spool show records crm:c-13 | awk '/^record/ {print $2}')
HALDEN=$(spool show records crm:c-5 | awk '/^identity/ {print $2}')
curl -s -X POST http://127.0.0.1:7765/v1/changesets -d '{"reason": "its invoices go to Leeds", "ops": [{"op": "assign", "record": "'$RECORD'", "from": null, "to": "'$HALDEN'"}]}'
Output
{"seq":3,"changeset":"01a1f0a8-23cd-735e-89c5-270748ed3dd2","content_hash":"3ceebd766a3780fc4c9a5143142ce86ac9e3833bd0a429e600b622a4475ce2dc"}
spool show review
Output
item  kind            status    type     raised by  about
1     possible_merge  resolved  company  run 9      1 record without an identity, which matched 2 identities

The item closed by itself. A possible_merge or a conflict is open while any of its records has no identity, and any changeset that places the last one resolves it.

An item closes in one of three ways:

  • Resolved. A changeset answered it. A reviewer may have written it, or a later match.
  • Superseded. A later run looked again and raised an item that differs, or found that the question no longer stands.
  • Dismissed. A reviewer closed it and left things as they are.

Open items are looked at again by every later match of their entity type. If the reviewer had fixed a rule so that the record matched only one identity, the next match would have placed the record and resolved the item.

A conflict

The British Halden Group now has a record with no country. Load a Halden Group in France:

halden-fr.csv
id,name,country
c-14,Halden Group,FR
spool load halden-fr.csv --source crm
spool match
spool show review --status open
Output
item  kind      status  type     raised by  about
2     conflict  open    company  run 12     1 record without an identity, which matched 1 identity

spool explain shows where it comes from:

spool explain crm:c-14 crm:c-13
Output
`crm:c-14` has no identity. `crm:c-13` belongs to identity 01a1efc6-41cd-775d-8758-e7329447fd9a.
Run 11 (strategy `rules`) judged them `match` (match rule `similar_name` held).
`crm:c-13` was placed at log position 3 by `user:01a1f0a0-a4da-74d5-bf74-28797e6632ab` ("its invoices go to Leeds").
Review item 2 (`conflict`) is open and names `crm:c-14`: the evidence about it contradicts itself, which is left to a reviewer.
By the rules as they are now, block rule `name_prefix` makes them a candidate pair and match rule `similar_name` holds, so they would be judged `match`.

left   4adcad34-e94d-d0d7-bd50-5ed0599dab66  crm:c-14  no identity
right  621ab95e-5f9e-6b91-e660-455831fe854a  crm:c-13  identity 01a1efc6-41cd-775d-8758-e7329447fd9a

features
            left          right
  country   FR            -
  name      Halden Group  Halden Group
  name_key  halden group  halden group

rules as they are now
  block     name_prefix        holds
  no_match  different_country  cannot be decided: a feature it reads is null
  match     similar_name       holds

runs that compared them
  run 11  rules  succeeded  block: name_prefix  match

review items that name them
  item 1 (possible_merge, resolved)
  item 2 (conflict, open)
spool explain crm:c-14 crm:c-5
Output
`crm:c-5` belongs to identity 01a1efc6-41cd-775d-8758-e7329447fd9a. `crm:c-14` has no identity.
Run 11 (strategy `rules`) judged them `no_match` (no_match rule `different_country` held).
`crm:c-5` was placed at log position 1 by `engine` (reconcile run 3, "reconcile new records").
Review item 2 (`conflict`) is open and names `crm:c-14`: the evidence about it contradicts itself, which is left to a reviewer.
By the rules as they are now, block rule `name_prefix` makes them a candidate pair and no_match rule `different_country` holds, so they would be judged `no_match`.

left   38f040c9-82b9-2f94-813b-697309e52dab  crm:c-5   identity 01a1efc6-41cd-775d-8758-e7329447fd9a
right  4adcad34-e94d-d0d7-bd50-5ed0599dab66  crm:c-14  no identity

features
            left          right
  country   GB            FR
  name      Halden Group  Halden Group
  name_key  halden group  halden group

rules as they are now
  block     name_prefix        holds
  no_match  different_country  holds
  match     similar_name       holds

runs that compared them
  run 11  rules  succeeded  block: name_prefix  no_match

review items that name them
  item 2 (conflict, open)

One member of the identity says yes and another says no, so the match left it. This is what a record with a missing value costs: it matches what a complete record would not. An earlier version of a row that was later corrected does the same, because earlier versions stay members, and go where the latest version is placed.

A reviewer who decides that the French company is not one to track dismisses the item:

ITEM=$(spool show review --status open | awk 'NR==2 {print $1}')
curl -s -X POST http://127.0.0.1:7765/v1/review/$ITEM/dismiss -d '{"reason": "a French company we do not track"}'
Output
{"id":2,"run":12,"entity_type":"company","kind":"conflict","records":["4adcad34-e94d-d0d7-bd50-5ed0599dab66"],"identities":["01a1efc6-41cd-775d-8758-e7329447fd9a"],"groups":[],"status":"dismissed","resolved_seq":null,"superseded_by":null,"dismissed":{"by":"user:01a1f0a0-a4da-74d5-bf74-28797e6632ab","at":"2026-11-18T21:47:02.755334Z","reason":"a French company we do not track"}}

The record stays without an identity, and later matches stop asking about it. A changeset can still place it.

A possible split

Records can be in one identity only because a third record joined them. Load a name that is close to "Acorn Tools Ltd" and not close enough to "Acorn Tools":

acorn.csv
id,name,country
c-15,Acorn Tools Limited,GB
spool load acorn.csv --source crm
spool match
spool explain crm:c-15 crm:c-1
Output
`crm:c-15` and `crm:c-1` belong to the same identity, 01a1efc6-41cd-775d-8758-e7300637659a.
Run 14 (strategy `rules`) made them a candidate pair (block rule `name_prefix`) and gave no judgement.
Nothing links the two directly. They are joined through 1 other member: `crm:c-15` → 31075f20-6900-838b-f5af-f8c6576744a4 (`match` in run 14) → `crm:c-1` (`match` in run 2).
`crm:c-15` was placed at log position 4 by `engine` (reconcile run 15, "reconcile new records").
`crm:c-1` was placed at log position 1 by `engine` (reconcile run 3, "reconcile new records").
By the rules as they are now, block rule `name_prefix` makes them a candidate pair and no `no_match` or `match` rule holds, so they would get no judgement.

left   8342b5e7-9fe2-8b68-d800-f7478cab83e5  crm:c-15  identity 01a1efc6-41cd-775d-8758-e7300637659a
right  ab8e9d59-0aaa-96b9-ddb7-db0bff7a9356  crm:c-1   identity 01a1efc6-41cd-775d-8758-e7300637659a

features
            left                 right
  country   GB                   GB
  name      Acorn Tools Limited  Acorn Tools
  name_key  acorn tools limited  acorn tools

rules as they are now
  block     name_prefix        holds
  no_match  different_country  does not hold
  match     similar_name       does not hold

runs that compared them
  run 14  rules  succeeded  block: name_prefix  no judgement

what joins them
  8342b5e7-9fe2-8b68-d800-f7478cab83e5 and 31075f20-6900-838b-f5af-f8c6576744a4: match in run 14
  31075f20-6900-838b-f5af-f8c6576744a4 and ab8e9d59-0aaa-96b9-ddb7-db0bff7a9356: match in run 2

It joined Acorn Tools through crm:c-3, Acorn Tools Ltd. Now the CRM deletes c-3, and the row is taken back:

spool retract --source crm --type company c-3 --reason "deleted in the CRM"
Output
run 16: 1 key named, 1 record taken back
1 record left an identity, by the changeset at log position 5
1 identity was left for review: what held its records together went through a record that was taken back. See `spool show review --status open`.
ITEM=$(spool show review --status open | awk 'NR==2 {print $1}')
spool show review $ITEM
Output
review item  3
kind         possible_split
status       open
type         company
raised by    run 16
identity     01a1efc6-41cd-775d-8758-e7300637659a

Are these records still one thing?
They share an identity, and a record that held them together was taken back by its source.
Each group below still holds together. Nothing the store knows joins one group to another:
no match found by a run, no `must_link`, and no decision by a reviewer or an agent.

group 1
  34c3d52d-e53b-1559-7404-1892fb1fd4e3  crm:c-9  still in the identity
  a780fcfe-cb2f-21dd-25ea-11db898fd6a2  crm:c-2  still in the identity
  ab8e9d59-0aaa-96b9-ddb7-db0bff7a9356  crm:c-1  still in the identity

group 2
  8342b5e7-9fe2-8b68-d800-f7478cab83e5  crm:c-15  still in the identity

taken back by their source, and no longer in the identity
  31075f20-6900-838b-f5af-f8c6576744a4  crm:c-3  in run 16

what answers it
  they are different things  split the identity: POST /v1/identities/01a1efc6-41cd-775d-8758-e7300637659a/split with the records of a group
  they are one thing         say so with a `must_link` between a record of each group: POST /v1/changesets
  leave it as it is          dismiss the item: POST /v1/review/3/dismiss
The review screen of the studio does each of these.

The identity is as it was, with crm:c-15 still in it. Nothing is split automatically: most identities that lose such a record are still one thing, and the item asks. The output lists the three answers. A reviewer who knows that Acorn Tools Limited is Acorn Tools says so with a must_link, which joins the groups whatever the rules say:

A=$(spool show records crm:c-1 | awk '/^record/ {print $2}')
B=$(spool show records crm:c-15 | awk '/^record/ {print $2}')
curl -s -X POST http://127.0.0.1:7765/v1/changesets -d '{"reason": "Acorn Tools Limited is Acorn Tools", "ops": [{"op": "constrain", "kind": "must_link", "a": "'$A'", "b": "'$B'"}]}'
Output
{"seq":6,"changeset":"01a1efa6-bf2c-7217-8a79-04156fcb171d","content_hash":"172d0850e8019236df5ba6d69400b732715ab3fa770cf699c7bef8d5de74295e"}
spool show review
Output
item  kind            status     type     raised by  about
1     possible_merge  resolved   company  run 9      1 record without an identity, which matched 2 identities
2     conflict        dismissed  company  run 12     1 record without an identity, which matched 1 identity
3     possible_split  resolved   company  run 16     4 records of one identity in 2 groups that nothing holds together

Drafts

A match commits its changeset by default. Started with "commit": false, it stores the changeset as a draft and changes nothing. That is how a new rule, or an agent, is tried against shared identities without touching them. spool match has no option for it, so this match is started over HTTP:

larkfield.csv
id,name,country
c-16,Larkfield logistics,GB
spool load larkfield.csv --source crm
curl -s -X POST http://127.0.0.1:7765/v1/match -d '{"entity_type": "company", "commit": false}'
DRAFT=$(spool show drafts --status open | awk 'NR==2 {print $1}')
spool show drafts $DRAFT
Output
draft            01a1f0a0-a840-778b-871c-76e67030b94b
type             company
status           open
from             match run 18, reconcile run 19
written against  log position 6
would place      1 record, 0 identities created

operations
  place record 5af84b72-c049-e1cc-0b28-2db7c0c0ef7d in 01a1efc6-41cd-775d-8758-e733aa086f7d

The draft is stored on the server, so whoever approves it need not be whoever started the match:

curl -s -X POST http://127.0.0.1:7765/v1/drafts/$DRAFT/approve
Output
{"seq":7,"changeset":"01a1f0a0-a840-778b-871c-76e67030b94b","content_hash":"4f962e11c6cc1f736c03d3b041ea04ab03e887c0852120db38068a158cdb4396"}
spool show drafts
Output
draft                                 type     status     operations  from
01a1f0a0-a840-778b-871c-76e67030b94b  company  committed  1           match run 18

Approving checks the draft like any changeset, against the identities as they are then. If they changed in a way that breaks it, the answer names the operations that no longer hold and the draft stays open. A draft can also be rejected, with POST /v1/drafts/<draft>/reject.

An entity type has at most one open draft. A later match of the type replaces it. The records of a draft that is rejected, replaced or never decided are examined again by the next match, so nothing is stranded.

Who reviews

A reviewer is anyone the server knows: a person signed in to the studio, or a program with a token. Each change is recorded under its author.

An agent connects at /mcp. For Claude Code against spool dev: claude mcp add --transport http spool http://127.0.0.1:7765/mcp. It has tools to list review items, read what is needed to decide one, explain a pair, commit a changeset, split an identity, undo a change and dismiss an item. Every one of those that changes something requires a reason. MCP lists them.

How many to expect

It depends on the rules. In the repository's benchmark on 5,000,000 voter records from five sources, the rules left 13,755 records for review. In its benchmark of data that changes, taking back 50,000 rows left 70 possible_split items.

What review does not have

  • Nothing notifies anyone that an item is waiting. Someone has to look.
  • Items are not assigned to people, and there is no queue or priority beyond the list.
  • The command line shows review items and drafts and cannot decide them.
  • An agent cannot approve or reject a draft. There is no MCP tool for it.