Section 17 · Pipeline Hygiene — Stop Losing Money to Messy CRM
17.4Find bad/inconsistent lost reasons
Built in the POC- No.
- 17.4
- DMA's reference
- Decision Book p.32
- Phase
- Phase 1
- Autonomy
- L1 · Recommend
- DMA's decision
- Yes
What DMA asked for · Decision Book p.32
Clean up bad or inconsistent lost reasons, so future scoring rests on reliable history.
Why it matters to DMA: It is the prerequisite for the deal autopsy and better scoring; the book says do it early.
In our words, from DMA's Product Decision Book v3, page 32.
How we do it
- The audit reads each lost deal's free-text reason and notes and maps it to one code from a fixed list: price, timing, existing agency, no budget, competitor, poor fit, other.
- Every code keeps the words it came from. If the words aren't found in the notes, the code is set to "not enough evidence" rather than guessed; codes outside the list are rejected.
- A cleaned, canonical lost reason can be written back to a Nutshell field, only under the rule for that field on the Fields screen (who may change it, at what autonomy).
The flow
It plays on its own while it's on screen; hover or use the controls to pause or step through.
Messy input
Nutshell says "$$ / went elsewhere".
- Nutshell
- AI
- Rule in code
- Stored data
Where the data goes
The same six stages on every page. Nothing reaches Nutshell except through the write gate.
- 1Nutshell
Source
Lost reasons and notes.
- 2Sync
Copies Nutshell changes into the bridge database
Mirrors them.
- 3Bridge database
A copy of the CRM data, plus what the AI works out
The code, its evidence and the audit run.
- 4AI
Claude models, only through DMA's own gateway
The audit maps text to a code; code checks it.
- 5Write gate
The only way back into Nutshell: checked, approved when needed, sent once
Writes the canonical reason only under its field rule.
- 6Nutshell
The system of record
One consistent lost reason per deal.
The tables behind it
Drawn from the POC's database catalogue: structure only, no data.
PK primary keyFK reference the database enforces (solid line)ID reference kept by id (dashed line)
| Table | What it holds | Columns |
|---|---|---|
| tax.nodes | The fixed list of lost-reason codes the audit may use. | 13 |
| crm.leads | Lost deals with their outcome. | 26 |
| ctrl.outbox | The write gate, for the canonical field. | 28 |
How the tables connect (3)
| Column | Points to | Kept by |
|---|---|---|
| tax.nodes.dimension | tax.taxonomy_versions | The database (foreign key) |
| tax.nodes.version | tax.taxonomy_versions | The database (foreign key) |
| ctrl.outbox.approval_id | ctrl.approvals | The database (foreign key) |
Worked example
Synthetic demo data: every name, business and number is made up.
Who may write the cleaned reason back
What you see
1.The field rules
The Fields screen says who may change each Nutshell field.
What happens in the system
- Rule engine
field_write.*Every AI-writable field has a rule and an autonomy level; changes to the sheet need a sign-off.
Three messy reasons and the codes the rules allow (synthetic demo data).
Lost reasons, cleaned
| In Nutshell | Code | Evidence |
|---|---|---|
| $$ / went elsewhere | Price | "chose a cheaper freelancer" (note, May 2025) |
| timing | Timing | "revisit after tax season" (note, Feb 2025) |
| ? | Not enough evidence | No note explains the loss |
In the running POC
Govern → Fields: who may change which Nutshell field, at what autonomy.
- 1The sign-off for the whole field sheet.
- 2One field and what the AI may do with it.
Dashboard · Govern → Fields. Captured from the running POC on September 25, 2026; synthetic data.
See it live
Opens the exact screen in the running POC, in a new tab.
| Open | Where | What to try |
|---|---|---|
| Fields | DMA AI dashboard | The rule for each Nutshell field the AI may write. |
Status
Built in the POC. This capability runs in the POC today, on synthetic data, end to end.