Section 6 · The 'Why Now?' Engine
6.5Ranking / visibility drop trigger
Designed for Phase 2- No.
- 6.5
- 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
If a strong old prospect loses search visibility, treat it as a legitimate reason to reach out.
Why it matters to DMA: It is timely, specific and exactly what DMA fixes, so the message is useful rather than a sales nudge.
In our words, from DMA's Product Decision Book v3, page 18.
How we do it
- DMA's book schedules this for Phase 2, with a search ranking feed. The POC already has everything the trigger feeds into; the feed itself is the Phase 2 work.
- Designed flow: the feed reports an event (a strong dormant prospect dropped for its main search terms). Rankings are tracked for the account's own domain and the terms that matter to its business, so the match is exact.
- The event becomes a dated signal on the account, like a contract end from a note. DMA's rules decide whether it changes the next best action, and the message angle is what dropped, since when, and the likely cause.
- Nothing reaches the prospect without the consent gate and the send limits, and new message angles are approved before use.
Already in place
- The website review the chat runs today already checks a site's search basics (titles, headings, speed and more) and names each issue with its evidence.
- The why-now slot on every account, with dated signals, their status and where they came from (6.1).
- Scoring and next-best-action rules kept as versioned data: a new trigger is a rule change a person approves, not new code paths.
- Consent, suppression, verified addresses and send limits on every message, whatever started it.
What the later phase adds
- Ranking tracking for the strongest dormant accounts (by score), on the terms that matter to them.
- A drop signal with the size of the drop and when it happened.
- A message angle that states the drop and offers the review, approved by DMA.
The flow
It plays on its own while it's on screen; hover or use the controls to pause or step through.
An event arrives
A strong dormant prospect dropped for its main search terms
- Stored data
- Rule in code
- Person
- Screen
Where the data goes
The same six stages on every page. Nothing reaches Nutshell except through the write gate.
- 1Event feed
Source
A search ranking feed (Phase 2).
- 2Sync
Copies Nutshell changes into the bridge database
Nutshell history is already mirrored; the event is matched against it.
- 3Bridge database
A copy of the CRM data, plus what the AI works out
Stores the event, the match and its confidence, with an expiry.
- 4AI
Claude models, only through DMA's own gateway
Reads the event and writes the angle; code decides the score and the action.
- 5Write gate
The only way back into Nutshell: checked, approved when needed, sent once
Carries the reason and next action onto the account.
- 6Nutshell
The system of record
The rep sees the event as the why-now.
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.site_reviews | The website review already used by the chat, reused to explain a drop. | 18 |
| ai.enrichment | Where bought-in data lands: provider, the fields returned, match confidence, cost and expiry. | 9 |
| ai.scores | The score, reason codes and next best action the event would feed. | 20 |
| ctrl.decision_log | Every trigger decision, with its inputs and the rule that fired. | 28 |
How the tables connect (6)
| Column | Points to | Kept by |
|---|---|---|
| ai.site_reviews.conversation_id | conv.conversations | The application (by id) |
| ai.site_reviews.prompt_id | agent.prompts | The application (by id) |
| ai.scores.prompt_id | agent.prompts | The application (by id) |
| ctrl.decision_log.agent_version_id | agent.agent_versions | The application (by id) |
| ctrl.decision_log.run_id | agent.runs | The application (by id) |
| ctrl.decision_log.conversation_id | conv.conversations | The application (by id) |
Worked example
Synthetic demo data: every name, business and number is made up.
Designed behaviour for one synthetic dormant account.
A ranking drop, as it would be recorded
| Search term | Position 60 days ago | Position now |
|---|---|---|
| emergency dentist austin | 2 | 9 |
| dental implants austin | 4 | 15 |
| northside dental | 1 | 1 |
In the running POC
There is no screen for this one yet: it is designed for Phase 2, as DMA's book decides. The parts listed under “Already in place” run in the POC today.
See it live
Opens the exact screen in the running POC, in a new tab.
| Open | Where | What to try |
|---|---|---|
| Today | DMA AI dashboard | Where the event would show as the why-now; today it shows the why-now from DMA's notes. |
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.