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 companiesspool devLeave 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 matchThe three kinds of item
| Kind | The question | Raised when |
|---|---|---|
possible_merge | Which identity does this record belong to? | A new record matches members of two or more identities. |
conflict | Does this record belong here or not? | A new record matches one member of an identity and a no_match rule holds against another. |
possible_split | Are 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:
id,name
c-13,Halden Groupspool load halden.csv --source crm
spool matchloaded 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 whyspool show reviewitem kind status type raised by about
1 possible_merge open company run 9 1 record without an identity, which matched 2 identitiesITEM=$(spool show review --status open | awk 'NR==2 {print $1}')
spool show review $ITEMreview 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-e7329447fd9aThe 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:

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'"}]}'{"seq":3,"changeset":"01a1f0a8-23cd-735e-89c5-270748ed3dd2","content_hash":"3ceebd766a3780fc4c9a5143142ce86ac9e3833bd0a429e600b622a4475ce2dc"}spool show reviewitem kind status type raised by about
1 possible_merge resolved company run 9 1 record without an identity, which matched 2 identitiesThe 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:
id,name,country
c-14,Halden Group,FRspool load halden-fr.csv --source crm
spool matchspool show review --status openitem kind status type raised by about
2 conflict open company run 12 1 record without an identity, which matched 1 identityspool explain shows where it comes from:
spool explain crm:c-14 crm:c-13`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`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"}'{"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":
id,name,country
c-15,Acorn Tools Limited,GBspool load acorn.csv --source crm
spool matchspool explain crm:c-15 crm:c-1`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 2It 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"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 $ITEMreview 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'"}]}'{"seq":6,"changeset":"01a1efa6-bf2c-7217-8a79-04156fcb171d","content_hash":"172d0850e8019236df5ba6d69400b732715ab3fa770cf699c7bef8d5de74295e"}spool show reviewitem 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 togetherDrafts
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:
id,name,country
c-16,Larkfield logistics,GBspool 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 $DRAFTdraft 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-e733aa086f7dThe 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{"seq":7,"changeset":"01a1f0a0-a840-778b-871c-76e67030b94b","content_hash":"4f962e11c6cc1f736c03d3b041ea04ab03e887c0852120db38068a158cdb4396"}spool show draftsdraft type status operations from
01a1f0a0-a840-778b-871c-76e67030b94b company committed 1 match run 18Approving 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.