Section 6 · The 'Why Now?' Engine
6.1Watch for a real reason to contact someone
Designed for Phase 2- No.
- 6.1
- DMA's reference
- Decision Book p.17
- Phase
- Phase 2
- Autonomy
- L2 · Prepare, then wait for approval
- DMA's decision
- Yes
What DMA asked for · Decision Book p.17
Reach out because something happened that gives a real reason to, not just because months have passed since the last contact.
Why it matters to DMA: A message tied to a real event gets far more replies than "it's been six months". DMA's book puts the outside-event feeds in Phase 2.
In our words, from DMA's Product Decision Book v3, page 17.
How we do it
- Every account already has a why-now, taken from DMA's own Nutshell history: a window the prospect gave ("call in Q1"), a "not before" date, a contract end, a proposal left open, a promise either side made. Code dates each one against the note it came from and says whether it is upcoming, current or passed.
- The why-now drives the score's timing factor, the next best action and the one-line reason on Today. Time since the last touch is only one input: a small account with nothing live is held back from outreach, however long it has been quiet.
- Phase 2 adds outside events (leadership changes, expansion, a site redesign, a ranking or reputation drop, funding). Each lands as another dated signal in the same place, so it flows through the same scoring, rules and approvals with no new path to the prospect.
- An outside event only ever proposes: outreach still goes through the consent gate, the send governor and, where DMA wants, a person's approval.
Already in place
- The why-now from DMA's own notes: dated facts, resolved by code, with the quote and the note they came from.
- Timing in the score and the next best action, from rules kept as versioned data that a person approves.
- A place in the database for bought-in company data (provider, match confidence, cost and an expiry), ready for the Phase 2 feeds.
- Consent, suppression and send limits that apply to any outreach, whatever triggered it.
What the later phase adds
- The event feeds DMA chooses (company news, hiring, funding, website changes, rankings, reviews), each behind its own switch and budget.
- Matching each event to the right account and contact, with a confidence; low-confidence matches go to a person.
- A trigger rule per event type in DMA's rules, and a message angle for each, approved like any other content.
- Reporting that compares reply rates for event-led and time-led outreach.
The flow
It plays on its own while it's on screen; hover or use the controls to pause or step through.
Today: the reason comes from DMA's notes
A window the prospect gave, a contract end or an open proposal is found in the notes and dated by code.
- Nutshell
- Stored data
- Rule in code
- Screen
Where the data goes
The same six stages on every page. Nothing reaches Nutshell except through the write gate.
- 1Nutshell and event feeds
Source
Today: the notes. Phase 2: outside events too.
- 2Sync
Copies Nutshell changes into the bridge database
Mirrors the notes; Phase 2 feeds land in the bridge database.
- 3Bridge database
A copy of the CRM data, plus what the AI works out
Keeps every signal with its date, its status and where it came from.
- 4AI
Claude models, only through DMA's own gateway
Finds the words in notes (and, later, reads events); code decides dates and scores.
- 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 why now on the account.
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 | Dated facts from notes: windows, contract ends, promises, with the exact quote. | 15 |
| ai.enrichment | Bought-in company data (Phase 2 feeds): provider, fields, match confidence, cost and expiry. | 9 |
| ai.scores | Score, reason codes and the next best action the rules chose. | 20 |
How the tables connect (2)
| 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) |
Worked example
Synthetic demo data: every name, business and number is made up.
What already runs: the why-now from DMA's own notes
What you see
1.Every revivable account has a reason
Today's list shows the why-now for each account, in words, with the note it came from.
What happens in the system
- Bridge database
ai.account_twinThe why-now is part of each account's current picture, rebuilt when its notes change.
- Rule engine
dating codeDates are resolved by code against each note's date; a passed window is never called upcoming.
Why-now lines as the POC writes them today, from synthetic notes. Outside events would add lines of the same shape.
Signals from DMA's own history (today)
| Signal | Why now, as shown | Effect |
|---|---|---|
| Contract end | Contract ends March 2027 (in 5 months) | Timing: contract ending |
| Window they gave | Their window opens Q1 2027 (in 3 months) | Timing: window ahead |
| Window passed | The window they gave (Q2 2026) has passed — the reason to wait is gone | Nothing left to wait for |
| Open proposal | Proposal sent May 2026 (4 months ago) | Proposal stage reached |
Designed for Phase 2: outside events
| Event | Why now, as it would show |
|---|---|
| New marketing leader | A new VP of Marketing started in September 2026 |
| New locations | Two new clinics opened in Austin in August 2026 |
| Ranking drop | Dropped out of the top three for "emergency dentist Austin" in the last 30 days |
In the running POC
Today: every revivable account with its why-now and the next best action.
- 1The why-now in words, with the note it came from.
- 2The next best action chosen by DMA's rules.
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 Why column shows each account's reason to contact now. |
Status
Designed for Phase 2. DMA's book schedules this for Phase 2. The design is ready and builds on parts that already run in the POC.