<aside> 💡 Use case: define what counts as a result, what each channel costs and which channel gets the credit, so the weekly report tells you where the money works.

</aside>

<aside> 👀 Who reads this folder: Results & ROI, and the orchestrator. Other folders point to kpi-model.md whenever they say "compared with your normal".

</aside>

kpi-model.md

<aside> 🎯 Controls: the one number that matters most, the KPI for each department, your normal per channel, and the shape of the weekly report.

How to fill it: define each number once, in plain words, with the tool it comes from. Set your own targets. Leave "Normal" blank: Results & ROI fills it from your data and names the period it used.

Save as brand-os/reporting/kpi-model.md.

</aside>

# KPI model

> Read by: results-roi, which reads Looker, BigQuery and Metabase.
> What you measure, how each number is defined, and what "normal" is. Other folders point here when they say
> "compared with your normal".
> Define a number once, here. Every report uses these definitions and says which one it used.

## The one number that matters most
- North star: [FILL IN: e.g. sales from social and search, booked jobs, sign-ups]
- Defined as: [FILL IN: exactly what is counted, and from which source]

## By department
| Department | KPI | Definition | Source | Target | Checked |
|---|---|---|---|---|---|
| Search visibility | [FILL IN: e.g. clicks from search] | [FILL IN] | [FILL IN: Google Search Console] | [FILL IN] | [FILL IN: weekly] |
| Market radar | [FILL IN] | [FILL IN] | [FILL IN] | [FILL IN] | [FILL IN] |
| Content engine | [FILL IN: e.g. pieces approved without edits] | [FILL IN] | [FILL IN: content-calendar.md] | [FILL IN] | [FILL IN] |
| Creative studio | [FILL IN] | [FILL IN] | [FILL IN] | [FILL IN] | [FILL IN] |
| Publishing & social | [FILL IN: e.g. engagement per post] | [FILL IN] | [FILL IN: Meta, LinkedIn, Metricool] | [FILL IN] | [FILL IN] |
| Reviews & reputation | [FILL IN: e.g. replies within your time] | [FILL IN] | [FILL IN: Google Business Profile] | [FILL IN] | [FILL IN] |
| Leads & conversations | [FILL IN: e.g. real leads] | [FILL IN] | [FILL IN: HubSpot] | [FILL IN] | [FILL IN] |
| Results & ROI | [FILL IN: e.g. cost per result by channel] | see margin-rules.md | [FILL IN] | [FILL IN] | [FILL IN] |

Example row (Northwind Coffee): | Leads & conversations | Wholesale leads | A HubSpot contact with lead source "chat" that passed routing-rules.md | HubSpot | [your target] | weekly |

## Your normal, by channel
Results-roi updates "Normal" from the data, names the period it used and never changes "Good".
| Channel | Main metric | Normal | Period it was measured over | Good |
|---|---|---|---|---|
| Instagram | [FILL IN] | | | [FILL IN] |
| LinkedIn | [FILL IN] | | | [FILL IN] |
| Facebook | [FILL IN] | | | [FILL IN] |
| TikTok | [FILL IN] | | | [FILL IN] |
| Articles | [FILL IN] | | | [FILL IN] |
| Newsletter | [FILL IN] | | | [FILL IN] |

## The weekly report
Results-roi writes it to drafts/YYYY-MM-DD-report-weekly.md with these parts:
1. The north star this week and last week, with the source
2. Each department KPI against target
3. What took off and what flopped (feeds content/hook-bank.md)
4. The margin watch (from margin-rules.md)
5. Questions it could not answer, and the data that was missing or stale

margin-rules.md

<aside> 💰 Controls: the margin watch: what each channel costs against what its results are worth, and when a channel is flagged.

How to fill it: enter what you actually pay and leave a cell blank rather than guess. The value of a result comes from your own sales records. Results & ROI only reports: any change to spend waits in queue/needs-your-ok.md and never passes owner/budget-cap.md.

Save as brand-os/reporting/margin-rules.md.

</aside>

# Margin rules

> Read by: results-roi. This is the margin watch: cost against result, per channel.
> Results-roi reports. It never moves money. Any change to spend goes to queue/needs-your-ok.md, and the
> total can never pass owner/budget-cap.md.

## What each channel costs
Fill in what you actually pay. Leave a cell blank rather than guess.
| Channel | Tool costs per month | Ad spend per month | Hours per month | Cost of an hour | Total cost |
|---|---|---|---|---|---|
| Instagram | [FILL IN] | [FILL IN] | [FILL IN] | [FILL IN] | |
| LinkedIn | [FILL IN] | [FILL IN] | [FILL IN] | [FILL IN] | |
| Facebook | [FILL IN] | [FILL IN] | [FILL IN] | [FILL IN] | |
| TikTok | [FILL IN] | [FILL IN] | [FILL IN] | [FILL IN] | |
| Search and articles | [FILL IN] | [FILL IN] | [FILL IN] | [FILL IN] | |
| Reviews | [FILL IN] | [FILL IN] | [FILL IN] | [FILL IN] | |
| Chat and DMs | [FILL IN] | [FILL IN] | [FILL IN] | [FILL IN] | |
| Shared tools (split across channels) | [FILL IN] | | | | |

How shared tools are split: [FILL IN: evenly, or by share of posts]

## What a result is worth
| Result | Counted in | Value of one |
|---|---|---|
| [FILL IN: a sale, a booked job, a lead, a sign-up] | [FILL IN: HubSpot, your shop, GA4] | [FILL IN: your real average, with where it comes from] |

Example row (Northwind Coffee): | Wholesale lead | HubSpot | [your average order value times your close rate, from your own sales records] |

## The margin watch
For each channel, every [FILL IN: week or month]:
- Cost per result = total cost / results credited (credit follows attribution.md)
- Margin = value of the results credited minus total cost

## When a channel is flagged
| Flag | Counts when | What happens |
|---|---|---|
| Losing money | [FILL IN: margin below the level you set, for how long] | a note in the weekly report and a row in queue/needs-your-ok.md |
| Cost rising | [FILL IN: rise in cost per result that counts] | a note in the weekly report |
| Room to grow | [FILL IN: the margin and volume that make it worth more spend] | a suggested increase in queue/needs-your-ok.md, within owner/budget-cap.md |

## Never
- Change a budget, a bid or a boost.
- Report a margin when the cost or the value cell is blank. Say which cell is missing.

attribution.md

<aside> 🔗 Controls: which channel gets the credit for a result, where results are counted, and how links are tagged so the credit can be traced.

How to fill it: pick one model from the table and keep it. Write the Google Analytics 4 event names and the HubSpot field you use. Name the gaps the model cannot see, so every report shows them.

Save as brand-os/reporting/attribution.md.

</aside>

# Attribution

> Read by: results-roi. Decides which channel gets the credit for a result, so margin-rules.md can compare channels fairly.
> Pick one model and keep it. Changing the model changes every comparison, so note the date you change it.

## The model we use
- Model: [FILL IN: one of the models below]
- Since: [FILL IN: date]

| Model | Credit goes to | Good when |
|---|---|---|
| Last touch | the last channel before the result | short decisions, one visit and buy |
| First touch | the first channel that brought them | you care most about new people finding you |
| Split evenly | every channel they touched, equally | longer decisions with several touches |
| Ask them | the channel they name when asked "how did you hear about us?" | small numbers, offline sales |

## Where a result is counted
- Website results: [FILL IN: the Google Analytics 4 key event names you use]
- Leads and deals: [FILL IN: the HubSpot field that holds the source]
- Offline or phone: [FILL IN: how you record the source]
- How long a touch still counts: [FILL IN: the lookback window you choose]

## Link tags (UTM)
Every link that leaves a post carries these. Publishing-social adds them.
| Tag | Rule | Example (Northwind Coffee) |
|---|---|---|
| utm_source | the platform, lower case | instagram |
| utm_medium | social, email, paid-social, review, chat | social |
| utm_campaign | YYYY-MM-topic | 2026-11-sampler |
| utm_content | the calendar ID | 003 |

## Known gaps
Results the model cannot see. Results-roi names these in every report instead of hiding them.
- [FILL IN: e.g. links shared in private messages, word of mouth, walk-ins]
- [FILL IN]

## Never
- Credit a result to two channels under a single-touch model.
- Fill a missing source with a guess. Mark it "unknown".

<aside> 👉 Next: The tool map

</aside>