Section 21 · Final Revenue Multipliers & Control Plane
21.4Margin-aware opportunity scoring
Designed for Phase 2- No.
- 21.4
- DMA's reference
- Decision Book p.45
- Phase
- Phase 2
- Autonomy
- L1 · Recommend
- DMA's decision
- Yes
◆ Amended in v3 of the book.
What DMA asked for · Decision Book p.45
Add predicted gross margin, delivery complexity, churn risk, service capacity and strategic value to the opportunity score.
Why it matters to DMA: It stops the AI treating the biggest contract as the best one: good revenue, not just big revenue.
In our words, from DMA's Product Decision Book v3, page 45.
How we do it
- DMA's book schedules this for Phase 2; it needs DMA's historical client economics and service capacity.
- The hook is already in the score: each service carries a margin weight that multiplies the score (bounded between 0.8 and 1.2). All weights are 1.0 until DMA provides its margins, so today it changes nothing.
Already in place
- A margin multiplier per service, applied to every score and shown in its reasons when it moves it.
- Churn reasons (fixable or not) already count in the history factor.
What the later phase adds
- DMA's real margins per service.
- Delivery complexity and capacity inputs.
- A backtest of the margin-aware version before approval.
The flow
It plays on its own while it's on screen; hover or use the controls to pause or step through.
Services that fit
Per account
- Stored data
- AI
- Routing
- Screen
Where the data goes
The same six stages on every page. Nothing reaches Nutshell except through the write gate.
- 1DMA's economics
Source
Margins per service (Phase 2).
- 2Sync
Copies Nutshell changes into the bridge database
Not involved.
- 3Bridge database
A copy of the CRM data, plus what the AI works out
Margin weights on the service list.
- 4AI
Claude models, only through DMA's own gateway
Not involved: scoring is code.
- 5Write gate
The only way back into Nutshell: checked, approved when needed, sent once
The adjusted score to Nutshell.
- 6Nutshell
The system of record
AI Score reflects margin.
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 | DMA's services, each with its margin weight (1.0 today). | 13 |
| ai.scores | The margin multiplier applied to each score. | 20 |
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) |
| ai.scores.prompt_id | agent.prompts | The application (by id) |
Worked example
Synthetic demo data: every name, business and number is made up.
Designed behaviour (synthetic margins).
Same size, different margin
| Deal | Margin weight | Score |
|---|---|---|
| SEO and local search | 1.1 | 88 |
| Paid search only | 0.9 | 72 |
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.
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.