Section 6 · The 'Why Now?' Engine

6.8Estimated agency-contract expiration

Built in the POC

No.: 6.8
DMA's reference: Decision Book p.18
Phase: Phase 2
Autonomy: L1 · Recommend
DMA's decision: Yes

What DMA asked for · Decision Book p.18

When DMA's notes say a prospect is tied to another agency, work out when that contract ends, so the lost reason turns into a dated follow-up.

Why it matters to DMA: "We're locked in with another agency" usually means "never" in a CRM. With a date, it becomes a follow-up on the calendar, at the one moment the prospect is free to move.

In our words, from DMA's Product Decision Book v3, page 18.

How we do it

The nightly review reads each account's Nutshell notes. When a note says who the current agency is or when their contract ends, the AI copies the exact words (for example "contract ends March") as a fact, with the note it came from.
Code, not the AI, turns those words into a date. It reads them against the note's own date, so "March" in a June 2026 note means March 2027. The AI's own reading is kept only for comparison.
Every dated fact gets a status against today: upcoming, current or passed. A passed contract end is never called "coming up": it says the contract may have renewed and to confirm before pitching.
The contract end feeds the score ("incumbent contract ending"), the why-now line and the next best action. A rule in DMA's scoring settings can hold the account until 60 days before the end date. When DMA uploads a signed contract and a person confirms its terms, that date, and the notice deadline that stops it renewing, outrank anything read from a note.

The flow

It plays on its own while it's on screen; hover or use the controls to pause or step through.

Step 1 of 6

A note mentions another agency

In June 2026 a rep wrote: they moved their SEO to BlueFin, the contract ends March, call in Q1.

Nutshell
AI
Rule in code
Stored data
Screen

Where the data goes

The same six stages on every page. Nothing reaches Nutshell except through the write gate.

1Nutshell notes
Source
The rep's own words about the other agency and its contract.
2Sync
Copies Nutshell changes into the bridge database
Mirrors the notes into the bridge database, encrypted.
3Bridge database
A copy of the CRM data, plus what the AI works out
Stores each fact with its quote, the note it came from and the date code worked out.
4AI
Claude models, only through DMA's own gateway
Finds and copies the words; code decides the date.
5Write gate
The only way back into Nutshell: checked, approved when needed, sent once
Carries the AI reason and next action onto the account.
6Nutshell
The system of record
The rep sees the reason and the date in Nutshell.

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
ai.extracted_facts	One row per fact found in a note: the exact quote, the note it came from, and the date as code resolved it.	15
ai.scores	The score, tier, reason codes, next best action and the date to wait until.	20
ai.account_twin	The account's current picture, including the why-now shown on Today.	16

How the tables connect (3)

Column	Points to	Kept by
ai.extracted_facts.prompt_id	agent.prompts	The application (by id)
ai.scores.prompt_id	agent.prompts	The application (by id)
ai.account_twin.prompt_id	agent.prompts	The application (by id)

Worked example

Synthetic demo data: every name, business and number is made up.

One account, from a note to the next action

1 / 4

What you see

1.Contract ends reach Today's list

An account whose reason is another agency's contract end sits in the top ten, with the reason in words and the next best action.

localhost:13301/

Today: the ten revivable accounts, each with its reason in words and the next best action.

What happens in the system

Bridge databaseai.account_twin · ai.scores
Today reads the current scores in DMA's one ranking order: tier, then score, then yearly value.
Rule enginescoring config v1
The reason "incumbent contract ending" comes from the timing factor; the dated fact is what makes it live.

Northside Dental Group, a synthetic former client in the demo data.

What the nightly review found in one note (15 June 2026)

Fact	Exact words in the note	What code made of it
Current agency	They moved their SEO to BlueFin	BlueFin
Contract end	contract ends March	March 2027 · upcoming
When to call	call Q1	Q1 2027 · upcoming
Spend	15k SEO	About $15,000 a month on SEO

What the team sees

Tier and score: Tier A · 85 of 100
Top reasons: Incumbent contract ending; former client, fixable churn; fits several services
Next best action: Win-back email to Dana
In words: Their SEO contract with BlueFin ends March 2027, and Q1 2027 is the call window, so send Dana a win-back email now.
Could be wrong if: They renew with BlueFin before March 2027, or the pricing issue that drove them away hasn't been fixed.

In the running POC

localhost:13301/

1 / 2Today: the ten revivable accounts, each with its reason in words and the next best action.

1A contract end with another agency (BlueFin), in words, with the note it came from.
2The next best action the rules picked.

Dashboard · Today. 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
Today	DMA AI dashboard	The top ten revivable accounts; the Why column shows each why-now.
Northside Dental Group	DMA AI dashboard	The contract end, the quote and the next best action.

Status

Built in the POC

Built in the POC. This capability runs in the POC today, on synthetic data, end to end.